.. _file_include_cmb_event.h: File cmb_event.h ================ |exhale_lsh| :ref:`Parent directory ` (``include``) .. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS Event queue manager for discrete event simulation. Provides routines to key clock sequencing and event scheduling. .. contents:: Contents :local: :backlinks: none Definition (``include/cmb_event.h``) ------------------------------------ .. toctree:: :maxdepth: 1 program_listing_file_include_cmb_event.h.rst Detailed Description -------------------- An event is defined as a function taking two pointers to void as arguments and returning void. The arguments are application defined, but the intention is to provide tuples of (action, subject, object) consisting of pointers to the event function and its two arguments. It will be called as ``*action(subject, object)`` when it is its turn. Afterward, control will return to the event dispatcher, which does not know the event specifics. Hence, no need to return indications of success or failure (or anything else) from the event function. The first argument ``void *subject`` can be understood as the implicit self or this pointer in an object-oriented language. It can be used as an identification, e.g., what object or process the event belongs to. Understood that way, the meaning becomes ``subject.action(object)``, i.e., a method of the subject class, acting on some other object. The event has an associated activation time and a priority. Just before the event is executed, the simulation time will jump to this time as the event is removed from the queue. The priority is a signed 16-bit integer, where a higher numeric value means a higher priority. If two events have equal activation time, the one with higher priority will execute first. If you need to ensure that some event executes after all other events at a particular time, use a large negative priority. If two events have the same activation time and the same priority, they will be executed according to first in first out (FIFO) order. When scheduled, an event handle will be assigned and returned. This is a unique event identifier and can be used as a reference for later cancelling, rescheduling, or reprioritizing the event. Behind the scene, the event queue is implemented as a hashheap where the event handle is a hash_key in the hash map and the event's current location in the heap is the hash map value. This gives O(1) cancellations and reschedules with no need to search the entire heap to find a future event. The details of the data structure are not exposed in this header file, see ``cmb_event.c`` for implementation. As always, the error handling is draconian. Functions for e.g., rescheduling an event will trip an assertion if the given event is not currently in the event queue. This is a deliberate design choice to ensure that bugs get fixed rather than "handled". Includes -------- - ``inttypes.h`` - ``stdbool.h`` - ``stdint.h`` - ``stdio.h`` Included By ----------- - :ref:`file_include_cimba.h` - :ref:`file_include_cmb_process.h` Functions --------- - :ref:`exhale_function_cmb__event_8h_1a4c3e9d9037829440f354114c9937f11f` - :ref:`exhale_function_cmb__event_8h_1a56ced982f078ecfd7fe5e27c82b90c05` - :ref:`exhale_function_cmb__event_8h_1a0f65958ae71e809a8d69326e4e81e460` - :ref:`exhale_function_cmb__event_8h_1a13b4e9b8e170c4572675c8c04ee09395` - :ref:`exhale_function_cmb__event_8h_1ac2e65b21de051d88edf4ce4287fcd667` - :ref:`exhale_function_cmb__event_8h_1a99e2d58815e09b141c5783f963af6022` - :ref:`exhale_function_cmb__event_8h_1a9dbd275a1c4bc2bba106dfbcfbaf84e0` - :ref:`exhale_function_cmb__event_8h_1afbf74d5b78e211a17488fdfa541bb2c8` - :ref:`exhale_function_cmb__event_8h_1a1d2e759ce71db2b45976b4e40275cbc4` - :ref:`exhale_function_cmb__event_8h_1a9fae5b31178cf8eaaaa0d8a8c622da75` - :ref:`exhale_function_cmb__event_8h_1a39445828af5d1cf412f00f6715c02eed` - :ref:`exhale_function_cmb__event_8h_1a2144f0b46aa46739df1983e89e257474` - :ref:`exhale_function_cmb__event_8h_1a6da4510a081fb367804d8157f711cf1d` - :ref:`exhale_function_cmb__event_8h_1a245dbcc52f38e9cb1fe2a6b2f40e7459` - :ref:`exhale_function_cmb__event_8h_1ad272215d2d425e3e94aa41ebd9512116` - :ref:`exhale_function_cmb__event_8h_1af3f9f967ff892944eed2f04f5353d8c9` - :ref:`exhale_function_cmb__event_8h_1a443aac4a190c15ed9b61821ee69ece38` - :ref:`exhale_function_cmb__event_8h_1a762266faf26949cc6304b6999782251b` - :ref:`exhale_function_cmb__event_8h_1a4ced1fe2f19180a6d05d35307ce0f0f1` - :ref:`exhale_function_cmb__event_8h_1a5b089b4ed5eb0e43a6a0c54047105838` Defines ------- - :ref:`exhale_define_cmb__event_8h_1a852f2123e90b49efb4dfe709fb662011` - :ref:`exhale_define_cmb__event_8h_1a6d889ee29fb3aeae768bd821a1c5defb` - :ref:`exhale_define_cmb__event_8h_1ab2d181770bb92cb0f5dd507df4a8fcd6` Typedefs -------- - :ref:`exhale_typedef_cmb__event_8h_1a8ed2f364a82b3b6da89cedd19b18aec5` - :ref:`exhale_typedef_cmb__event_8h_1afc4ce5e2e58241188b254fd6329927a4`