Appendix R - Registering Special Functions

• Registering Event Functions -

  To register a function to be called before each event, use CSIM_AddEventLoopFunc, which is formally defined as:

  void CSIM_AddEventLoopFunc( EventLoopFunc func, void *data );

  Example Usage:

  /* In DEFINE_GLOBAL area. */
  void my_event_function( int x )
  { printf("Next event. %d\n", x); }

  ...
  /* Somewhere in your model code under or called by a model-thread, */
  CSIM_AddEventLoopFunc( my_event_function, aparameter );

  Functions registered with CSIM_AddEventLoopFunc above, are called just prior to the next event, or pre-event execution. The prior event has already been removed from the time-schedule-queue. The next event is at the head of the queue. CSIM_TIME has advanced to the time of the next event.

  Alternatively, there are situations where it is necessary to register functions to execute post-event, That is, after an event has executed, but before CSIM_TIME is advanced, and before the event is removed from the time-schedule-queue. An example of this situation is functions that may need to schedule events before the next event. Register such functions with the following post-event registering function, CSIM_AddEventLoopPostFunc which is formally defined as:

  void CSIM_AddEventLoopPostFunc( EventLoopFunc func, void *data );

  It is like CSIM_AddEventLoopFunc above, but functions registered with this function will be called at the end of events before time is advanced.

• Registering Initialization Functions -

  To register functions to be called once, before the first event of a simulation begins, use CSIM_AddInitializationFunc. It is formally defined as:

  void CSIM_AddInitializationFunc( EventLoopFunc func, void *data )

  It can be used for example to open logging files that will remain open for the duration of a simulation.

  (This feature is available in version 4.37, and beyond, of CSIM.)

• Registering Exit Functions -

  To register a function to be called when the simulation exits, use CSIM_AddExitFunc, which is formally defined as:

  void CSIM_AddExitFunc( EventLoopFunc func, void *data )

  It can be used to close logging files, generate summaries, etc..

  Note that for many simulations, the CSIM_EndOfSim synchron can be used as an alternative to registering an exit function. It triggers your closing threads to print final results and close files. However, that method applies to simulations having activity for only finite durations. Simulations which have no definite ending, -which produce events forever-, will never activate the CSIM_EndOfSim synchron. For indefinite duration simulations, registering an exit function may be more useful.

  Example Usage:

  /* In DEFINE_GLOBAL area. */
  void my_exit_function( int x )
  { printf("Closing time. Experiment %d.\n", x); }

  ...
  /* Somewhere in your model code under or called by a model-thread, */
  CSIM_AddExitFunc( my_exit_function, casenumber );