Improving the message sending APIs

[dominiklohmann]

send/request currently have a lot of duplicated code, because there are a lot of variations of the functions. I believe these are all of them:

	send	request	send_exit	delegate
anon	yes	no	yes	no
delayed	yes	yes	no	no
scheduled	yes	yes	no	no

Now with #1222 there is another modifier proposed, which is weak. This also relates to #1189.

I propose extending the message_priority template parameter to a more general message_policy template parameter, that can have either of the following values.

• anonymous
• delayed
• scheduled
• weak
• urgent (as a replacement for message_priority::high)

If necessary, the following policy parameters can be added to explicitly use the normal way:

• onymous (explicitly not anonymous)
• instant (explicitly neither delayed nor scheduled)
• strong (explicitly not weak)
• nonurgent (as a replacement for message_priority::normal)

With these being a template argument it should be easy to detect impossible policy combinations at compile time to give proper error messages. E.g., self->request<anonymous> cannot work, and self->send<delayed + scheduled> doesn't make sense either.

Not quite sure on the exact naming, but I wanted to get this idea out here. What do you think @Neverlord?

[Neverlord]

Thanks for putting this together! It's always a good exercise to step back and get a new perspective on things.

Since you asked for my thoughts, here are a couple of initial questions/considerations that I had while reading your post in no particular order.

Regarding the anon versions: they stand on their own, because they are free functions. They also exist as member functions for historic reasons that date back to ~2014 when request was still called sync_send, but if we are evaluating them in the context of today, we could argue the member functions on actors just shouldn't exist. Adding the anonymous qualifier would force us to continue supporting the member function versions.

Scheduled and delayed requests are not a thing at the moment. They are proposed, but the API would have non-intuitive implications. Requests have a relative timeout. Scheduled/delayed send ships the message after a timeout expires. So when should the timer on the request start? Consider: self->request<delayed>(buddy, 1s, 2s, "hey there")..., which one's the timeout for the delayed part now? Is it sending after 1 second and then waits up to two seconds for a response? The opposite? In any case, I'd have to read the documentation to figure it out. That's why I'd still prefer something like run_delayed(1s, [=] { self->request(buddy, 2s, "hey there")...; }). Granted, this uses one more messaging roundtrip. However, it's more generic and I can see what's happening without consulting the docs.

The proposed weak probably only makes sense on scheduled or delayed send.

As a user, would I find this new API easier to learn or use? I think template parameters that change the signature of a function add another level of complexity: send(receiver, ...) but send<delayed>(receiver, timeout, ...). There's also the combinatorial aspect that you've already mentioned and that many combinations of qualifiers are ruled out. Also, CAF is already quite heavy on templates and this extra template parameters at least have the potential to make compiler errors even worse.

As a maintainer, I wonder whether the extra complexity introduced by more templates pays for the potential reduction in code.

[dominiklohmann]

Regarding the anon versions: they stand on their own, because they are free functions. [...] but if we are evaluating them in the context of today, we could argue the member functions on actors just shouldn't exist.

Makes sense.

So when should the timer on the request start? Consider: self->request<delayed>(buddy, 1s, 2s, "hey there")..., which one's the timeout for the delayed part now?

That's a good point from the API UX side of things. self->request<delayed>(buddy, delay(1s), timeout(2s), "hey there") could work here without requiring the need to introduce an extra roundtrip, and it makes the API really clear.

run_delayed(1s, [=] { self->request(buddy, 2s, "hey there")...; })

How would this work for the proposed weak modifier? A separate run_weak_delayed? I think this contains an equal amount of ways to do something unexpected.

As a maintainer, I wonder whether the extra complexity introduced by more templates pays for the potential reduction in code.

Ultimately, this and the compiler error situation are up to you. Really glad we're discussing this, though, as I've recently wanted some form of self->weak_delayed_request(self, ...) and implementing that currently is no fun at all.

[Neverlord]

That's a good point from the API UX side of things. self->request<delayed>(buddy, delay(1s), timeout(2s), "hey there") could work here without requiring the need to introduce an extra roundtrip, and it makes the API really clear.

That's not quite what I meant. 🙂

I should've picked just send as an example:

• self->send(buddy, 1s, "hey there"): will send {1s, "hey there"}
• self->send<delayed>(buddy, 1s, "hey there"): will send {"hey there"}?

I believe template parameters that change the signature of a function can make the API quite unwieldy to learn/navigate. Without delayed, the function takes one parameter (receiver), followed by the contents for the message. With the delayed, the function now must take two function parameters (receiver and delay), followed by the contents for the message.

I can see the approach work for weak and urgent (plus anonymous if we'd want to include it), but not for modifiers that would have to change the function signature.

However, the picture would change if we were to break up the API using a DSL. For example:

  self->mail(1, 2, 3).after(1s).to(buddy).send();
  self->mail(1, 2, 3).after(1s, weak).to(buddy).request(1s).then(...);
  self->mail(1, 2, 3).urgent().to(buddy).anon_send();
  self->mail(1, 2, 3).to(buddy).delegate();

Or with a bit less method chaining:

  self->mail(1, 2, 3).after(1s).send(buddy);
  self->mail(1, 2, 3).schedule(now() + 5s, weak).request(buddy, 1s).then(...);
  self->mail(1, 2, 3).urgent().send(buddy, anonymous);
  self->mail(1, 2, 3).delegate(buddy);

The weak modifier only affects delayed (and scheduled) messages, so I think it makes sense to tie these two together. An anonymous request makes no sense to me (and delegate always keeps the sender information of the currently processed message), so it'd still keep send, request and delegate as separate operations and anonymous is only applicable to send.

So basically, I see send, request, and delegate as the actual operations and the modifiers are delayed|scheduled and urgent. The modifiers can be freely combined with any of the operations. The only thing that slightly bugs me is that a send with a delay should return the disposable. So either the return type changes depending on whether or not you choose a delay or we'd have to always return a disposable, whether it's actually being used or not. Plus, it'd break the request(...).then(...) chaining. Although that could just be request(...).first.then(...) instead, so it wouldn't be too bad.

We do have actors that can send but don't support request. Not a showstopper, though. Just means we'll have two versions for the DSL.

On thing that makes this DSL quite intriguing for me is that there's only a single entrypoint into the dsl: mail. Which means it's a single member function at an actor and we could get rid of mixin::sender and mixin::requester eventually (after a transition phase + deprecation cycle).

@dominiklohmann, @riemass: thoughts?

[dominiklohmann]

I like the DSL approach. Some initial thoughts:

• With self->mail(...).anon_send(...), how do I replace usage of caf::anon_send as a free function without a sender? Something like caf::anon_mail(...).anon_send(...)?
• I like the version with less chaining a lot better than the version with more of it. It makes more sense for delegate as well, as self->mail(...).delegate(rp) makes more sense than self->mail(...).to(rp).delegate() when reading.
• What happens if I don't finish a mail builder, e.g., by never calling send, request, or delegate? Does the actor's error handler get called? Can I create a mail builder, store it, and then later send the mail using it?
• I assume that request returns a response handle. Does it make sense to take a look at modernizing that as well, while you're working on these APIs? For example, when the receiver is a typed actor it would be awesome to just be able to write request(hdl).then([](auto x) { /* decltype(x) is expected<T>, where T is inferred automatically */})?

[riemass]

Some feedback, after reading through the discussion and tickets:

• the second version of the API looks better. The to call would add little information to the DSL and introduce overhead, lengthen the compiler warnings, might confuse the users (does it go second, does it go last?), etc.
• this was on my mind for a while, we could unify scheduled and delayed (in the example called after) into one interface, and overload on the provided type. If it's a duration type, behave as the current delayed (now() + duration), and for time points types like scheduled.
• Even if we don't unify the calls, I'd rather stick with delay instead of after, and make a connection with the well known delayed_send.
• I think the anon_send free function is a must. Sometimes you don't have a sender, and don't need the overhead of a scoped_actor. I like the anon_mail interface @dominiklohmann suggested, I'd even loose the second anon and just leave it like caf::anon_mail(...).send(...).
• self->mail(1, 2, 3).send(buddy, anonymous); just feels out of place. It's a method and it has a sender. We can keep the interface just for the variety of it, but if we're going to have an anon_mail then I'd rater loose this.
• Would you consider a sane default for scheduled and after to always be weak, with the overload of strong?

[Neverlord]

Thanks for the feedback! I think we have consensus on the version with less chaining. I like that version better as well. 🙂

• What happens if I don't finish a mail builder, e.g., by never calling send, request, or delegate? Does the actor's error handler get called? Can I create a mail builder, store it, and then later send the mail using it?

I think an unfinished builder shouldn't be a thing. Marking all steps [[nodiscard]] and only providng && overloads should keep it simple and hard-to-misuse.

• I assume that request returns a response handle. Does it make sense to take a look at modernizing that as well, while you're working on these APIs? For example, when the receiver is a typed actor it would be awesome to just be able to write request(hdl).then([](auto x) { /* decltype(x) is expected<T>, where T is inferred automatically */})?

Technically not an issue, but doing it this way would break the symmetry with the dynamically typed API.

• this was on my mind for a while, we could unify scheduled and delayed (in the example called after) into one interface, and overload on the provided type. If it's a duration type, behave as the current delayed (now() + duration), and for time points types like scheduled.
• Even if we don't unify the calls, I'd rather stick with delay instead of after, and make a connection with the well known delayed_send.

I think keeping them separate keeps the API a bit clearer, but I think keeping the terminology is probably for the better, i.e., delay and schedule.

• I think the anon_send free function is a must. Sometimes you don't have a sender, and don't need the overhead of a scoped_actor. I like the anon_mail interface @dominiklohmann suggested, I'd even loose the second anon and just leave it like caf::anon_mail(...).send(...).

Yeah, good point. anon_mail() can just be a free function and then we don't need a parameter for send.

• Would you consider a sane default for scheduled and after to always be weak, with the overload of strong?

The current default is strong and I think that's what most uses would call for. However, maybe we just don't pick a default at all for the new API. We can still relax that in some future version.

In any case, I think I'll get started on a first draft version of the new API and then we have something more concrete to discuss.