1 During client library implementation, few things to keep in mind.
3 Threads and locking in client library
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.
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.
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.
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.
48 The client library internals are to be rewritten with SILC FSM and all
49 major operations should be implemented as FSM.
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.
57 When to use FSM semaphore signalling?
59 FSM semaphore 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_SEMA_POST 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).
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 semaphore signalling.
72 Semaphore signals should be pre-allocated SilcFSMSemaStruct structures
73 and for signalling use they are always initialized as:
75 silc_fsm_sema_init(&sema, fsm, 0);
77 The call cannot fail. Semaphores need not be uninitialized and the same
78 context may be reused.
80 Finishing threads when closing connection
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 threads as they are always waiting for a command. If any thread is
86 waiting for something else than a command (such as event threads) they
87 must be explicitly finished. The threads are finished by continuing
88 them synchronously. The threads will detect that we are disconnected
89 (see below). SILC_FSM_YIELD must be returned in st_close() as that
90 gives the FSM scheduler time to finish the threads first. After that
91 the machine can be finished.
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
96 if (conn->internal->disconnected)
99 If disconnected the thread must finish immediately by returning