Added SILC Thread Queue API

[crypto.git] / lib / silcclient / README

diff --git a/lib/silcclient/README b/lib/silcclient/README
index 66a14e7d072148aa85b4744ca57376063a251623..7a475336b636ff7bdb2e546f0b0f04ae10d616e5 100644 (file)
--- a/lib/silcclient/README
+++ b/lib/silcclient/README
@@ -54,25 +54,60 @@ Using FSM
    threads that need execution time also.
 
 
-When to use FSM semaphore signalling?
+When to use FSM event signalling?
 
-   FSM semaphore signalling should be used only when multiple threads
+   FSM event signalling should be used only when multiple threads
    (FSM threads) may be waiting for something to happen.  If only one thread
    is waiting for something it should merely return SILC_FSM_WAIT and when
    that something happens it should use silc_fsm_continue or
    silc_fsm_continue_sync to continue in the waiting thread.  OTOH, if
-   multiple threads are waiting SILC_FSM_SEMA_POST is the only way to
+   multiple threads are waiting SILC_FSM_EVENT_SIGNAL is the only way to
    deliver the signal.  Always remember that posting is signal is not
    donbe synchronously (it won't be delivered immediately).
 
    OTOH, if there is only one thread waiting for somtehing to happen but
    there can be multiple threads signalling that something has happened
-   only way to do this is to use semaphore signalling.
+   only way to do this is to use event signalling.
 
-   Semaphore signals should be pre-allocated SilcFSMSemaStruct structures
+   Event signals should be pre-allocated SilcFSMEventStruct structures
    and for signalling use they are always initialized as:
 
-     silc_fsm_sema_init(&sema, fsm, 0);
+     silc_fsm_event_init(&event, fsm);
 
-   The call cannot fail.  Semaphores need not be uninitialized and the same
+   The call cannot fail.  Events need not be uninitialized and the same
    context may be reused.
+
+Finishing threads when closing connection
+
+   When closing SilcClientConnection all threads must first be finished
+   before the connection machine is finished.  This is done by finishing
+   all running command threads.  That will also finish all waiting packet
+   and notify threads as they are always waiting for a command.  If any
+   thread is waiting for something else than a command (such as event
+   threads) they must be explicitly finished.  The threads are finished by
+   continuing them synchronously.  The threads will detect that we are
+   disconnected (see below).  SILC_FSM_YIELD must be returned in
+   st_close() as that gives the FSM scheduler time to finish the threads
+   first.  After that the machine can be finished.
+
+   Also, any thread that runs in SilcClientConnection machine must always
+   after returning from wait state to check if we are disconnected by doing
+
+     if (conn->internal->disconnected) {
+       xxx;
+       return SILC_FSM_FINISH;
+     }
+
+   If disconnected the thread must finish immediately by returning
+   SILC_FSM_FINISH.
+
+Entry locking
+
+   All entires have a read/write lock.  It is used to protect the entries
+   when library updates them at the same time application is reading data
+   from the entries.  An API for application to read-lock the entires
+   exist.  Library only needs to use write-lock.  Using read-lock is not
+   necessary inside library because all connection related stuff, including
+   updating connection related entries are done in one thread.  When library
+   is reading data from the entries it cannot be updating them at the same
+   time.  Hence, using read-lock inside library is not necessary.