Re: [Qemu-devel] [PATCH 4/5] coroutine-lock: make qemu_co_enter_next thread-safe

[Paolo Bonzini <pbonzini@redhat.com>]

On 29/01/2018 08:26, Stefan Hajnoczi wrote:
>>  /**
>> - * Enter the next coroutine in the queue
>> + * Immediately enter the next coroutine in the queue.  Release the mutex
>> + * while it runs.
> 
> s/mutex/lock/
> 
> Is this doc comment correct?  I see multiple cases due to aio_co_wake():
> 
> 1. Called from coroutine context with current AioContext matching next
>    coroutine's AioContext: arrange for next coroutine to be entered
>    *after* we yield (not "immediately").
> 
> 2. Called from non-coroutine context with current AioContext matching
>    next coroutine's AioContext: immediately enter next coroutine.
> 
> 3. Called from different AioContext than next coroutine: arrange for
>    next coroutine to be entered at some point.

Good point, it needs to be more specific.  Here is the best I could come up
with:

+ * Removes the next coroutine from the CoQueue, and wake it up.
  * Returns true if a coroutine was removed, false if the queue is empty.
  */
 bool coroutine_fn qemu_co_queue_next(CoQueue *queue);

...

+ * Empties the CoQueue; all coroutines are woken up.
  */
 void coroutine_fn qemu_co_queue_restart_all(CoQueue *queue);

...

+ * Removes the next coroutine from the CoQueue, and wake it up.  Unlike
+ * qemu_co_queue_next, this function releases the lock during aio_co_wake
+ * because it is meant to be used outside coroutine context; in that case, the
+ * coroutine is entered immediately, before qemu_co_enter_next returns.
+ *
+ * If used in coroutine context, qemu_co_enter_next is equivalent to
+ * qemu_co_queue_next.
  */
 #define qemu_co_enter_next(queue, lock) \
     qemu_co_enter_next_impl(queue, QEMU_MAKE_LOCKABLE(lock))