From: Timo Sirainen <timo.sirainen@dovecot.fi>
Date: Mon, 11 Dec 2017 23:04:29 +0000 (+0200)
Subject: lib: ioloop.h - improve ioloop context comments
X-Git-Tag: 2.3.0.rc1~104
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4b51ecbac8e207266f04f61c8a5f36558665d61f;p=thirdparty%2Fdovecot%2Fcore.git

lib: ioloop.h - improve ioloop context comments
---

diff --git a/src/lib/ioloop.h b/src/lib/ioloop.h
index 853b470cb0..9f792387f1 100644
--- a/src/lib/ioloop.h
+++ b/src/lib/ioloop.h
@@ -146,15 +146,27 @@ void io_loop_set_current(struct ioloop *ioloop);
 void io_loop_add_switch_callback(io_switch_callback_t *callback);
 void io_loop_remove_switch_callback(io_switch_callback_t *callback);
 
-/* This context is used for all further I/O and timeout callbacks that are
-   added until returning to ioloop. When a callback is called, this context is
-   again activated. */
+/* Create a new ioloop context. This context is automatically attached to all
+   the following I/Os and timeouts that are added until the context is
+   deactivated (e.g. returning to back to a running ioloop). Whenever such
+   added I/O or timeout callback is called, this context is automatically
+   activated.
+
+   Creating this context already deactivates any currently running context
+   and activates the newly created context. */
 struct ioloop_context *io_loop_context_new(struct ioloop *ioloop);
 void io_loop_context_ref(struct ioloop_context *ctx);
 void io_loop_context_unref(struct ioloop_context **ctx);
 /* Call the activate callback when this context is activated (I/O callback is
    about to be called), and the deactivate callback when the context is
-   deactivated (I/O callback has returned). You can add multiple callbacks. */
+   deactivated (I/O callback has returned). You can add multiple callbacks.
+
+   The ioloop context is a global state, so only a single context can be active
+   at a time. The callbacks are guaranteed to be called only at their proper
+   states, i.e. activate() callback is called only when switching from
+   no context to the active context, and deactive() is called only when
+   switching from previously activated context into no context. No context is
+   active at a time when the ioloop is destroyed. */
 void io_loop_context_add_callbacks(struct ioloop_context *ctx,
 				   io_callback_t *activate,
 				   io_callback_t *deactivate, void *context);