X-Git-Url: http://git.silcnet.org/gitweb/?p=crypto.git;a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcfsm.h;h=503b8f43eafebff4ad8f81992582c095dca56e66;hp=b23e36efb296f95d5eb6613ea6372c063f12ab5c;hb=60180da59ffdbbd12058dded66e3c8a547cd0852;hpb=8fd8212bcd16f2b53fbedff2a9b9a4e8c15b9695

diff --git a/lib/silcutil/silcfsm.h b/lib/silcutil/silcfsm.h
index b23e36ef..503b8f43 100644
--- a/lib/silcutil/silcfsm.h
+++ b/lib/silcutil/silcfsm.h
@@ -117,8 +117,8 @@ typedef struct SilcFSMObject SilcFSMThreadStruct;
  *
  * DESCRIPTION
  *
- *    Moves to next state synchronously.  This type is used is returned
- *    from state functions to immediately move to next state.
+ *    Moves to next state synchronously.  This type is returned from state
+ *    functions to immediately move to next state.
  *
  * EXAMPLE
  *
@@ -291,7 +291,7 @@ typedef int (*SilcFSMStateCallback)(struct SilcFSMObject *fsm,
  ***/
 #define SILC_FSM_CALL(function)			\
 do {						\
-  assert(!silc_fsm_set_call(fsm, TRUE));	\
+  SILC_VERIFY(!silc_fsm_set_call(fsm, TRUE));	\
   function;					\
   if (!silc_fsm_set_call(fsm, FALSE))		\
     return SILC_FSM_CONTINUE;			\
@@ -364,7 +364,8 @@ do {						\
  *
  *    Macro used to wait for the `thread' to terminate.  The machine or
  *    thread will be suspended while it is waiting for the thread to
- *    terminate.
+ *    terminate.  The machine or thread will continue once the waited
+ *    thread has terminated.
  *
  * NOTES
  *
@@ -402,6 +403,9 @@ do {						\
  *    caller must free the returned context with silc_fsm_free.  The
  *    `fsm_context' is delivered to every FSM state function.  The `schedule'
  *    is the caller's scheduler and the FSM will be run in the scheduler.
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try
+ *    get global scheduler.  Returns NULL on error or if system is out of
+ *    memory.
  *
  * EXAMPLE
  *
@@ -447,7 +451,9 @@ SilcFSM silc_fsm_alloc(void *fsm_context,
  *    as argument.  The silc_fsm_free must not be called if this was called.
  *    Returns TRUE if the initialization is Ok or FALSE if error occurred.
  *    This function does not allocate any memory.  The `schedule' is the
- *    caller's scheduler and the FSM will be run in the scheduler.
+ *    caller's scheduler and the FSM will be run in the scheduler.  If
+ *    `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
  *
  * EXAMPLE
  *
@@ -480,7 +486,8 @@ SilcBool silc_fsm_init(SilcFSM fsm,
  *    thread context with silc_fsm_free.  If the 'real_thread' is TRUE
  *    then the thread will actually be executed in real thread, if platform
  *    supports them.  The `thread_context' is delivered to every state
- *    function in the thread.
+ *    function in the thread.  Returns NULL on error or if the system is out
+ *    of memory.
  *
  * NOTES
  *
@@ -491,8 +498,11 @@ SilcBool silc_fsm_init(SilcFSM fsm,
  *    for the FSM thread. If you need scheduler in the real thread it is
  *    strongly recommended that you use the SilcSchedule that is allocated
  *    for the thread.  You can retrieve the SilcSchedule from the thread
- *    using silc_fsm_get_schedule function.  Note that, the allocated
- *    SilcSchedule will become invalid after the thread finishes.
+ *    using silc_fsm_get_schedule function.  The new scheduler is a child
+ *    scheduler of the original scheduler used with `fsm'.  Note that, the
+ *    allocated SilcSchedule will become invalid after the thread finishes.
+ *    Note also that the scheduler is automatically set as global scheduler
+ *    in that thread by calling silc_schedule_set_global.
  *
  *    If `real_thread' is FALSE the silc_fsm_get_schedule will return
  *    the SilcSchedule that was originally given to silc_fsm_alloc or
@@ -904,7 +914,8 @@ typedef struct SilcFSMEventObject SilcFSMEventStruct;
  *    some event happens, some thread moves to a specific state or similar.
  *    The FSM Events may also be used in FSM threads that are executed in
  *    real system threads.  It is safe to wait and signal the event from
- *    threads.
+ *    threads.  The `fsm' must be the machine, not a thread.  Returns NULL
+ *    if system is out of memory or `fsm' is not FSM machine.
  *
  *    Use the macros SILC_FSM_EVENT_WAIT and SILC_FSM_EVENT_TIMEDWAIT to wait
  *    for the event.  Use the SILC_FSM_EVENT_SIGNAL macro to signal all the
@@ -923,7 +934,8 @@ SilcFSMEvent silc_fsm_event_alloc(SilcFSM fsm);
  *
  *    Initializes a pre-allocates FSM event context.  This call is
  *    equivalent to silc_fsm_event_alloc except this use the pre-allocated
- *    context.  This fuction does not allocate any memory.
+ *    context.  This fuction does not allocate any memory.  The `fsm'
+ *    must be the machine, not a thread.
  *
  ***/
 void silc_fsm_event_init(SilcFSMEvent event, SilcFSM fsm);