From 6c623b55bd023d9b2afa6ac3d69d814475a493e4 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Thu, 25 Sep 2003 19:48:48 +0000 Subject: Patch from Metze to document events interface (This used to be commit 228c03ce663ecbb76df06590aaa87a8dba2fc0c7) --- docs/docbook/devdoc/modules.xml | 166 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 165 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docbook/devdoc/modules.xml b/docs/docbook/devdoc/modules.xml index 171ee27f90..3adf130911 100644 --- a/docs/docbook/devdoc/modules.xml +++ b/docs/docbook/devdoc/modules.xml @@ -7,7 +7,14 @@
jelmer@samba.org
- 19 March 2003 + + StefanMetzmacher + +
metze@metzemix.de
+ + events interface + + 17 September 2003 Modules @@ -161,4 +168,161 @@ be used as probing will most likely disappear in the future. + + +Registration of events + + +Intention + + +For some modules it is necessary to drop idle database connections, +or do other things periodically. +Some modules need to do close database connections or similar things +when the server exits. + + + + + +Advantages + + +The event registration system has the following advantages: + + + +Every module is able to register/unregister idle or exit handlers called from the main server loop +No need for hacking the main server anymore + + + + + +General stuff + + +Each event has an event_id of type smb_event_id_t, which identifies the event in its event list. +(Take a look at include/module.h and lib/module.c.) +There are currently two event types: + + + +idle events +exit events + + + + + +Type: idle event + + +Idle events are called periodically from the main server loop. +if the specified interval is less or equal than 0, the default SMB_IDLE_EVENT_DEFAULT_INTERVAL (180 s) is used. +if the specified interval is less than SMB_IDLE_EVENT_MIN_INTERVAL (30 s), SMB_IDLE_EVENT_MIN_INTERVAL is used. +In any other case the specified interval is used. + + + +the real interval can be differ from the specified interval about up to +/- 30 s. + + + +Idle events can be registered via the + +smb_event_id_t smb_register_idle_event(smb_idle_event_fn *fn, void *data, time_t interval); + function. + + + + +fn + +the function pointer to idle handler function. +this function must have the following prototype! + +void example_idle_event_fn(void **data, time_t *interval, time_t now); + + + + +data +this is a pointer to private data which is passed to the idle function when it's called. + + +interval + +this is a pointer to the time_t interval in witch the idle handler function is called. +the idle handler is able to change it's interval. + + + + + +the event_id is returned on succes, on failure SMB_EVENT_ID_INVALID is returned. + + + +Idle events can be unregistered via the + +BOOL smb_unregister_idle_event(smb_event_id_t id); + function. + + + +True is returned on success, False on failure. + + + + + +Type: exit event + +Exit events are called when the server exits + + +Exit events can be registered via the + +smb_event_id_t smb_register_exit_event(smb_exit_event_fn *fn, void *data); + function. + + + + +fn + +the function pointer to exit handler function. +this function must have the following prototype! + +void example_exit_event_fn(void **data); + + + + +data +this is a pointer to private data which is passed to the exit function when it's called. + + + + + +the event_id is returned on success, on failure SMB_EVENT_ID_INVALID is returned. + + + +Exit events can be unregistered via the + +BOOL smb_unregister_exit_event(smb_event_id_t id); + function. + + + +True is returned on succes, False on failure. + + + + + + -- cgit