[Idea] C++20 coroutines inside agent's event_handler? The first take

[eao197]

These are my first thoughts about supporting C++20 coroutines inside an agent's event_handler.

I'm not going to try to fantasize about the purposes that coroutines in event_handler can be used for. It doesn't matter for now. Just assume that we want to have a possibility to write something like that:

class my_agent : public so_5::agent_t
{
  void so_define_agent() override
  {
    so_subscribe_self().event(
      [](mhood_t<some_msg> cmd) -> so_5::resumable_t {
        ...
        co_await some_expression();
        ...
      });
  }
};

The first key moment is a special return value type -- so_5::resumable_t (the name can be changed if something more appropriate will be found).

The next key moment is a special handling of event_handlers that return so_5::resumable_t. When an event_handler uses so_5::resumable_t as the return type then SO-5 will understand that event_handler is a coroutine and will do some special transformation. Let's suppose that we have something like that:

class my_agent : public so_5::agent_t
{
  so_5::resumable_t evt_some_handler(mhood_t<some_msg> cmd);
  ...
  void so_define_agent() override
  {
    so_subscribe_self().event(&my_agent::evt_some_handler);
  }
};

This code will be "transformed" into something like this:

class my_agent : public so_5::agent_t
{
  // The special hidden signal to be used for resumption.
  struct _msg_resume_current_coroutine final : public so_5::signal_t {};

  // The resumable object returned by a coroutine.
  so_5::resumable_t _m_current_resumable{ nullptr };

  // The special and hidden handler that will be called when
  // _msg_resume_current_coroutine arrives.
  void _evt_resume(mhood_t<_msg_resume_current_coroutine> cmd) {
    _m_current_resumable.resume();
    if(_m_current_resumable.done()) {
      // Coroutine finished, we have to return to normal work.
      _m_current_resumable.destroy();
      so_drop_subscription(
        so_direct_mbox(),
        so_current_state(),
        &my_agent::_evt_resume);

      _so_reactivate_normal_processing();
    }
  }

  // The special and hidden handler that will be subscribed to
  // some_msg instead of evt_some_handler.
  void _evt_auto_generated_for_some_msg(mhood_t<some_msg> cmd) {
      // We need a subscription for the hidden signal.
      so_subscribe_self().event(&my_agent::_evt_resume);

      // We need to pause normal delivery of pending demands
      // to this agent.
      _so_deactivate_normal_processing();

      // Get a resumable object for the coroutine.
      _m_current_resumable = this->evt_some_handler(std::move(cmd));

      // Just return the control back to the dispatcher.
  }

  // Coroutine to be used as an event_handler.
  so_5::resumable_t evt_some_handler(mhood_t<some_msg> cmd);

  void so_define_agent() override
  {
    so_subscribe_self().event(
      &my_agent::_evt_auto_generated_for_some_msg);
  }
}

The next key moment is the presence of two special methods _so_deactivate_normal_processing and _so_reactivate_normal_processing.

In the normal processing mode there is an event_queue with pending demands (at the moment such a queue belongs to dispatchers, agents do not own these queues).

A demand in the queue holds information about one incoming message and how it should be processed (as normal message or as evt_start/evt_finish special signals). A dispatcher takes the first pending demand, calls an event_handler and then goes to the next pending demand if any.

It could be a case where the demand queue for my_agent holds several pending demands:

some_msg
another_msg
and_yet_another_msg

The dispatcher gets the first one (for some_msg) and calls the event_handler for it. It will be the special _evt_auto_generated_for_some_msg handler that just stores the resumable object into _m_current_resumable and returns.

The dispatcher sees that event_handled completed and takes the next demand from the queue.

But this normal processing is not appropriate when the event_handler for some_msg is a coroutine. In this case the normal processing has to be paused and the agent should react to _msg_resume_current_coroutine signals only.

The new hypothetical methods _so_deactivate_normal_processing and _so_reactivate_normal_processing are intended for switching from normal processing mode to the special one, and for returning back to the normal mode.

When the agent switches to this special mode it will look like switching to a different and empty demand queue, the old demand queue will be stored somewhere. This new queue will be used for _msg_resume_current_coroutine signals only. All other messages will be redirected to the old queue (they will be stored to the old queue, but the processing will be delayed).

When _msg_resume_current_coroutine arrives it will be extracted and delivered to _evt_auto_generated_for_some_msg handler the usual way. The SO-5 will see such a signal just as usual without a need for a special handling.

And the next key moment is to use _msg_resume_current_coroutine signal for resumption of a suspended coroutine. The promise and awaitables for SO-5 have to be written in such a way to send _msg_resume_current_coroutine when coroutine has to be resumed.

---

This is a very basic idea with a lot of white spots.

The main of them is how to implement this changing of demand queues for an agent. It seems to me that the work on this old idea has to be resumed. If an agent has its custom event_queue then it could be changed to any other queue when it's appropriate and necessary.

Another white spot is support coroutine-based thread safe event handlers on adv_thread_pool dispatcher. The example shown above requires changing of the agent internal members for processing coroutine, but those changes are prohibited in thread safe event handlers. I hope the solution will be found. Even if this won't happen in the near future the first implementation for support of coroutines could be made for non-thread safe event handlers. With the hope that the solution will be found with time.

---

I think that one way to add support for C++20 coroutines into SO-5 is to use a special mark that enables coroutine-based event_handlers for an agent. Something like that:

class my_agent : public so_5::agent_t
{
  my_agent(context_t ctx)
    : so_5::agent_t{ctx + so_5::enable_courotines}
  {}
};

An attempt to subscribe an event_handler that returns so_5::resumable_t without addition of so_5::enable_coroutines to the agent context will lead to an exception during subscription.

I also think that SO-5.8 will still require C++17 as the minimum, the support for coroutines will be available only if SO-5 is being compiled in C++20/23 mode.

[ilpropheta]

Hey @eao197, thanks for sharing! That's an interesting topic. I would be interested in the (experimental) code, if you have some that can be disclosed.

I think the main point worth highlighting is the purpose of coroutines in agents (I know you were a bit reluctant at the beginning of the discussion): they (can) enable better concurrency without breaking the actor model.

Coroutines give dispatchers more flexibility in thread usage. For example, if two agents share a one_thread dispatcher, they run on the same context thread. If one handler can suspend, the dispatcher can resume another agent, then return to the first when ready, improving responsiveness. The same principle applies to thread pools, where suspension points help avoid long tasks monopolizing threads.

However, for agents bound to dedicated threads, the benefit is less evident, but coroutines can still simplify asynchronous workflows and integrate with modern async APIs.

What do you think?

[eao197]

I would be interested in the (experimental) code, if you have some that can be disclosed.

No, there is nothing to share yet. I hope to do some first experiments before the New Year, but nothing working will be available until the end of January 2026 (at best).

If one handler can suspend, the dispatcher can resume another agent, then return to the first when ready, improving responsiveness.

Yes, this is what some users asked us. Especially in relation to synchronous interaction between agents.

However, for agents bound to dedicated threads, the benefit is less evident, but coroutines can still simplify asynchronous workflows and integrate with modern async APIs.

An interesting topic is integration with Asio on asio-based dispatchers from so5extra.
It also can open new possibilities for integrating SO-5 into other frameworks.

[eao197]

Another white spot is support coroutine-based thread safe event handlers on adv_thread_pool dispatcher.

Maybe this case has a natural and simple solution: when an agent uses own custom event queue, then it pushes a special execution_demand into the dispatcher queue. This execution_demand has to be treated as not-thread-safe one, because it will modify internal agent's state (extraction of the actual pending message from the custom queue).

It means that agents with custom event queues simply can't have thread-safe event handlers.

"Can't" means that an agent can make a subscription with the thread_safe flag, but this flag will be ignored and all event handlers will be treated as if they are not thread-safe.