sven
/
libicsneo
mirror of https://github.com/intrepidcs/libicsneo.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Added documentation for event callbacks

checksum-failure-logging
EricLiu2000 2019-08-05 11:41:01 -04:00
parent 1aeee082ae
commit 451f0a9ac1
1 changed files with 18 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
docs/Usage.rst
View File

@ -15,6 +15,8 @@ Those of severity ``Error`` are referred to as "errors", which use a separate er
Events should periodically be read out in order to avoid overflowing, and the last error should be read out immediately after an API function fails. Events should periodically be read out in order to avoid overflowing, and the last error should be read out immediately after an API function fails.
Additionally, `event callbacks`_ can be registered, which may remove the need to periodically read events in some cases.
.. _events: .. _events:
Events Events
@ -29,6 +31,20 @@ When events are read out by the user, they are removed from the buffer. If an ev
In a multithreaded environment, all threads will log their events to the same buffer. In this case, the order of events will largely be meaningless, although the behavior of ``TooManyEvents`` is still guaranteed to be as described above. In a multithreaded environment, all threads will log their events to the same buffer. In this case, the order of events will largely be meaningless, although the behavior of ``TooManyEvents`` is still guaranteed to be as described above.
.. _event callbacks:
Event Callbacks
~~~~~~~~~~~~~~~~~~~~
Users may register event callbacks, which are automatically called whenever a matching event is logged.
Message callbacks consist of a user-defined ``std::function< void( std::shared_ptr<APIEvent> ) >`` and optional EventFilter used for matching.
If no EventFilter is provided, the default-constructed one will be used, which matches any event.
Registering a callback returns an ``int`` representing the id of the callback, which should be stored by the user and later used to remove the callback when desired.
Note that this functionality is only available in C and C++. C does not currently support filters.
Event callbacks are run after the event has been added to the buffer of events. The buffer of events may be safely modified within the callback, such as getting (flushing) the type and severity of the triggering event.
Using event callbacks in this manner means that periodically reading events is unnecessary.
.. _errors: .. _errors:
Errors Errors
@ -65,8 +81,9 @@ Message Callbacks and Polling
In order to handle messages, users may register message callbacks, which are automatically called whenever a matching message is received. In order to handle messages, users may register message callbacks, which are automatically called whenever a matching message is received.
Message callbacks consist of a user-defined ``std::function< void( std::shared_ptr<Message> ) >`` and optional message filter used for matching. Message callbacks consist of a user-defined ``std::function< void( std::shared_ptr<Message> ) >`` and optional message filter used for matching.
If no message filter is provided, the default-constructed one will be used, which matches any message.
Registering a callback returns an ``int`` representing the id of the callback, which should be stored by the user and later used to remove the callback when desired. Registering a callback returns an ``int`` representing the id of the callback, which should be stored by the user and later used to remove the callback when desired.
Note that this functionality is only available in C and C++. Note that this functionality is only available in C and C++. C does not currently support filters.
The default method of handling messages is to enable message polling, which is built upon message callbacks. The default method of handling messages is to enable message polling, which is built upon message callbacks.
Enabling message polling will register a callback that stores each received message in a buffer for later retrieval. Enabling message polling will register a callback that stores each received message in a buffer for later retrieval.