Continued the war against cruft. Don't touch utmp anymore; always use the output...

[citadel.git] / citadel / techdoc / citadel_thread_io.txt

diff --git a/citadel/techdoc/citadel_thread_io.txt b/citadel/techdoc/citadel_thread_io.txt
index c397ba3cf7c6feabcb7a30b2123885abed6aaf3b..bdcae91cfc3f999f1daefc28722510a93ad5557d 100644 (file)
--- a/citadel/techdoc/citadel_thread_io.txt
+++ b/citadel/techdoc/citadel_thread_io.txt
@@ -60,11 +60,12 @@ All other have to implement their own IO controled business logic.
 
 ===== IO-Thread =====
 The IO-Event-queue lives in this thread. Code running in this thread has to obey several rules.
-  - it mustn't do blocking operations (like disk IO) 
+  - it mustn't do blocking operations (like disk IO or nameserver lookups other than the c-ares facilities) 
   - it mustn't use blocking Sockets
   - other threads mustn't access memory belonging to an IO job
   - New IO contexts have to be registered via QueueEventContext() from other threads; Its callback are then called from whithin the event queue to start its logic.
   - New HTTP-IO contexts have to be registered via QueueCurlContext() 
+  - once you've registered a context, you must not access its memory anymore to avoid race conditions.
 
 ==== Logic in event_client ====
 InitIOStruct() which prepares an AsyncIO struct for later use before using QueueEventContext() to activate it.
@@ -96,3 +97,5 @@ Usually a context should respect that there may be others around also wanting to
 While its ok to do _some_ requests in a row (like deleting some messages, updating messages, etc.),
 loops over unknown numbers of queries should be unrolled and be done one query at a time (i.e. looking up messages in the 'already known table')
 
+=== Transitioning back & forth ===
+If the application logic has found that a transition is to be made from the event IO to the DB IO thread. Do so by calling DBQueueEventContext() (DB -> IO) EventQueueDBOperation() (IO->DB) and pass its return value up the row to enable the controll logic to do the actual transition for you.