lib/silcclient/README

   1 During client library implementation, few things to keep in mind.
   2
   3 Threads and locking in client library
   4
   5    The client library is multithreaded in so that the actual SilcClient
   6    runs in one main thread (may be application main thread or its created
   7    thread for the client), and each connection to a remote host runs in
   8    an own thread.  There are no other threads in client library.  If there
   9    is only one connection in the client, then most likely there is only
  10    one thread in addition of main thread.
  11
  12    The SilcClient context must be protected with lock (client->internal->lock),
  13    because it may be accessed from connection threads and by application.
  14    It is guaranteed that the client main thread never access the connection
  15    thread, and it is guaranteed that no other connection thread access
  16    another connection thread.  Even still, the SilcClientConnection has
  17    a lock (conn->internal->lock) because it may be accessed by application.
  18
  19    Practically everything in the client is executed in the connection thread.
  20    Receiving packets, commands, notifys, etc all happen in connection thread.
  21    It is not possible to receive packets in two different threads that would
  22    be destined to one specific connection thread.  But, because packets and
  23    commands may be sent from application thread the connection lock is
  24    used to protect shared data in the SilcClientConnection.  It is, however,
  25    guaranteed that the main client thread, or other connection thread will
  26    not send any packets or commands to another connection.  When remembered
  27    this makes programming easier.  Everything happens in one thread that
  28    has something to do with the connection.  When packet is received and
  29    it is processed asynchronously, it is always guaranteed that it is
  30    processed in that same thread, even if it is processed asynchronously.
  31    No other thread will process it.  If it is processed synchronously, no
  32    other packet may arrive at the same time, not for that connection.
  33    But it is possible that while we are processing incoming command reply,
  34    application sends another command from application thread.  Because of
  35    this, the lock exist in the connection context.
  36
  37
  38 Using locks
  39
  40    Use locking only if necessary.  For performance reasons SILC Atomic
  41    Operations API should be preferred if it can be used to achieve what
  42    needs to be achieved.  All reference counters must be atomic integers
  43    and locking must not be used with them.
  44
  45
  46 Using FSM
  47
  48    The client library internals are to be rewritten with SILC FSM and all
  49    major operations should be implemented as FSM.
  50
  51    Always return SILC_FSM_CONTINUE if you need to move to next state
  52    synchronously.  Use SILC_FSM_YIELD if you are in FSM thread and
  53    peformance is not an issue, but only if there really are other FSM
  54    threads that need execution time also.
  55
  56
  57 When to use FSM event signalling?
  58
  59    FSM event signalling should be used only when multiple threads
  60    (FSM threads) may be waiting for something to happen.  If only one thread
  61    is waiting for something it should merely return SILC_FSM_WAIT and when
  62    that something happens it should use silc_fsm_continue or
  63    silc_fsm_continue_sync to continue in the waiting thread.  OTOH, if
  64    multiple threads are waiting SILC_FSM_EVENT_SIGNAL is the only way to
  65    deliver the signal.  Always remember that posting is signal is not
  66    donbe synchronously (it won't be delivered immediately).
  67
  68    OTOH, if there is only one thread waiting for somtehing to happen but
  69    there can be multiple threads signalling that something has happened
  70    only way to do this is to use event signalling.
  71
  72    Event signals should be pre-allocated SilcFSMEventStruct structures
  73    and for signalling use they are always initialized as:
  74
  75      silc_fsm_event_init(&event, fsm);
  76
  77    The call cannot fail.  Events need not be uninitialized and the same
  78    context may be reused.
  79
  80 Finishing threads when closing connection
  81
  82    When closing SilcClientConnection all threads must first be finished
  83    before the connection machine is finished.  This is done by finishing
  84    all running command threads.  That will also finish all waiting packet
  85    and notify threads as they are always waiting for a command.  If any
  86    thread is waiting for something else than a command (such as event
  87    threads) they must be explicitly finished.  The threads are finished by
  88    continuing them synchronously.  The threads will detect that we are
  89    disconnected (see below).  SILC_FSM_YIELD must be returned in
  90    st_close() as that gives the FSM scheduler time to finish the threads
  91    first.  After that the machine can be finished.
  92
  93    Also, any thread that runs in SilcClientConnection machine must always
  94    after returning from wait state to check if we are disconnected by doing
  95
  96      if (conn->internal->disconnected) {
  97        xxx;
  98        return SILC_FSM_FINISH;
  99      }
 100
 101    If disconnected the thread must finish immediately by returning
 102    SILC_FSM_FINISH.
 103
 104 Entry locking
 105
 106    All entires have a read/write lock.  It is used to protect the entries
 107    when library updates them at the same time application is reading data
 108    from the entries.  An API for application to read-lock the entires
 109    exist.  Library only needs to use write-lock.  Using read-lock is not
 110    necessary inside library because all connection related stuff, including
 111    updating connection related entries are done in one thread.  When library
 112    is reading data from the entries it cannot be updating them at the same
 113    time.  Hence, using read-lock inside library is not necessary.