viewvc/hybrid-ircservices-1/modules.h

/* Module support include file (interface definition).
 *
 * IRC Services is copyright (c) 1996-2009 Andrew Church.
 *     E-mail: <achurch@achurch.org>
 * Parts written by Andrew Kempe and others.
 * This program is free but copyrighted software; see the file GPL.txt for
 * details.
 */

#ifndef MODULES_H
#define MODULES_H

/*************************************************************************/

/* Version code macro.  Parameters are:
 *      major: Major version number (the "5" in 5.1a0).
 *      minor: Minor version number (the "1" in 5.1a0).
 *     status: Release status (alpha, prerelease, or final).  Use one of
 *             the MODULE_VERSION_{ALPHA,PRE,FINAL} macros:
 *                5.1a0   -> MODULE_VERSION_ALPHA
 *                5.1pre0 -> MODULE_VERSION_PRE
 *                5.1.0   -> MODULE_VERSION_FINAL
 *    release: Release number (the "0" in 5.1a0).
 */
#define MODULE_VERSION(major,minor,status,release) (            \
    ((major) > 5 || ((major) == 5 && (minor) >= 1))             \
        ? ((major)<<24 | (minor)<<16 | (status)<<12 | (release))\
        : (0x050000 | (release))                                \
)
#define MODULE_VERSION_ALPHA    0xA
#define MODULE_VERSION_PRE      0xB
#define MODULE_VERSION_FINAL    0xF

/* Version code for modules.  This will be updated whenever a change to the
 * program (structures, callbacks, etc.) makes existing binary modules
 * incompatible.  This is stored in the compiled modules and used to let
 * Services determine whether a given module is compatible with the current
 * binary; it can also be used with #if to make source code compatible with
 * multiple versions of Services.
 */
#define MODULE_VERSION_CODE     MODULE_VERSION(5,1,MODULE_VERSION_FINAL,0)

/*************************************************************************/

/* Module information.  The actual structure is defined in module.c, and is
 * opaque to the caller. */
struct Module_;
typedef struct Module_ Module;

/* Callback function prototype. */
typedef int (*callback_t) ();

/* Callback priority limits. */
#define CBPRI_MIN       -10000
#define CBPRI_MAX       10000

/*************************************************************************/

/* Macro to rename a symbol based on the module's ID (MODULE_ID) in order
 * to avoid symbol clashes.  This roundabout construction is necessary to
 * force the preprocessor to substitute the value of MODULE_ID instead of
 * appending "MODULE_ID" literally. */

#define RENAME_SYMBOL(symbol) RENAME_SYMBOL_2(symbol,MODULE_ID)
#define RENAME_SYMBOL_2(symbol,id) RENAME_SYMBOL_3(symbol,id)
#define RENAME_SYMBOL_3(symbol,id) symbol##_##id

/*************************************************************************/

/* Macros to retrieve a pointer to the current module or its name. */

#ifdef MODULE
# define THIS_MODULE RENAME_SYMBOL(_this_module)
#else
# define THIS_MODULE NULL
#endif

#define MODULE_NAME (get_module_name(THIS_MODULE))

/*************************************************************************/
/*************************************************************************/

/* External variable/function declarations.  Note that many of the
 * functions below are macroized to automatically pass a "current-module"
 * parameter; functions whose names begin with "_" should not be called
 * directly. */

/*************************************************************************/

/* Initialization and cleanup: */

extern int modules_init(int ac, char **av);
extern void modules_cleanup(void);
extern void unload_all_modules(void);

/*************************************************************************/

/* Module-level functions: */

/* Load a new module and return the Module pointer, or NULL on error. */
extern Module *load_module(const char *modulename);

/* Remove a module from memory.  Return nonzero on success, zero on
 * failure. */
extern int unload_module(Module * module);

/* Return the Module pointer for the named module, or NULL if no such
 * module exists. */
extern Module *find_module(const char *modulename);

/* Increment or decrement the use count for the given module.  A module
 * cannot be unloaded while its use count is nonzero. */
#define use_module(mod)   _use_module(mod,THIS_MODULE)
#define unuse_module(mod) _unuse_module(mod,THIS_MODULE)
extern void _use_module(Module * module, const Module * caller);
extern void _unuse_module(Module * module, const Module * caller);

/* Re-read configuration files for all modules.  Return nonzero on success,
 * zero on failure. */
int reconfigure_modules(void);

/*************************************************************************/

/* Module symbol/information retrieval: */

/* Retrieve the value of the named symbol in the given module.  Return NULL
 * if no such symbol exists.  Note that this function should not be used
 * for symbols whose value might be NULL, because there is no way to
 * distinguish a symbol value of NULL from an error return.  For such
 * symbols, or for cases where a symbol might legitimately not exist and
 * no error should be printed for nonexistence, use check_module_symbol(). */
#define get_module_symbol(mod,symname) \
    _get_module_symbol(mod,symname,THIS_MODULE)
extern void *_get_module_symbol(Module * module, const char *symname,
                                const Module * caller);

/* Check whether the given symbol exists in the given module; return 1 if
 * so, 0 otherwise.  If `resultptr' is non-NULL and the symbol exists, the
 * value is stored in the variable it points to.  If `errorptr' is non-NULL
 * and the symbol does not exist, a human-readable error message is stored
 * in the variable it points to. */
extern int check_module_symbol(Module * module, const char *symname,
                               void **resultptr, const char **errorptr);

/* Retrieve the name of the given module. */
extern const char *get_module_name(const Module * module);

/*************************************************************************/

/* Callback-related functions: (all functions except register_callback()
 * and call_callback() return nonzero on success and zero on error)
 */

/* Register a new callback list. */
#define register_callback(name) _register_callback(THIS_MODULE,name)
extern int _register_callback(Module * module, const char *name);

/* Call all functions in a callback list.  Return 1 if a callback returned
 * nonzero, 0 if all callbacks returned zero, or -1 on error.  The _N
 * formats allow passing parameters. */
#define call_callback(id) \
    call_callback_1(id, NULL)
#define call_callback_1(id,arg1) \
    call_callback_2(id, arg1, NULL)
#define call_callback_2(id,arg1,arg2) \
    call_callback_3(id, arg1, arg2, NULL)
#define call_callback_3(id,arg1,arg2,arg3) \
    call_callback_4(id, arg1, arg2, arg3, NULL)
#define call_callback_4(id,arg1,arg2,arg3,arg4) \
    call_callback_5(id, arg1, arg2, arg3, arg4, NULL)
#define call_callback_5(id,arg1,arg2,arg3,arg4,arg5) \
    _call_callback_5(THIS_MODULE, id, (void *)(long)(arg1), \
                     (void *)(long)(arg2), (void *)(long)(arg3), \
                     (void *)(long)(arg4), (void *)(long)(arg5))
extern int _call_callback_5(Module * module, int id, void *arg1, void *arg2,
                            void *arg3, void *arg4, void *arg5);

/* Delete a callback list. */
#define unregister_callback(name) _unregister_callback(THIS_MODULE,name)
extern int _unregister_callback(Module * module, int id);

/* Add a function to a callback list with the given priority (higher
 * priority value = called sooner).  Callbacks with the same priority are
 * called in the order they were added. */
#define add_callback_pri(module,name,callback,priority) \
    _add_callback_pri(module,name,callback,priority,THIS_MODULE)
int _add_callback_pri(Module * module, const char *name, callback_t callback,
                      int priority, const Module * caller);

/* Add a function to a callback list with priority 0. */
#define add_callback(module,name,callback) \
    add_callback_pri(module,name,callback,0)

/* Remove a function from a callback list. */
#define remove_callback(module,name,callback) \
    _remove_callback(module,name,callback,THIS_MODULE)
extern int _remove_callback(Module * module, const char *name,
                            callback_t callback, const Module * caller);

/*************************************************************************/
/*************************************************************************/

/* Module functions: */

int init_module(void);
int exit_module(int shutdown);

/*************************************************************************/

/* Macros to declare a symbol to be exported.  Only one may be used per
 * line, and it must be placed at the beginning of the line and be the only
 * thing on the line (no semicolon at the end).  This does not have any
 * actual effect on compilation, but such lines are extracted to create
 * module symbol lists.  Note that it is not necessary to explicitly list
 * the init_module, exit_module, and module_config symbols (and in fact,
 * doing so will cause an error when linking the final executable).
 *
 * Also note that typedefs cannot be used here; use struct tags instead.
 *
 * Examples:
 *     EXPORT_VAR(const char *,s_NickServ)
 *     EXPORT_ARRAY(some_array)
 *     EXPORT_FUNC(create_akill)
 */

#define EXPORT_VAR(type,symbol)
#define EXPORT_ARRAY(symbol)
#define EXPORT_FUNC(symbol)

/*************************************************************************/
/*************************************************************************/

/* Internal-use stuff. */

/*************************************************************************/

/* Pointer to the current module.  This is defined in each module's main
 * source file, and automatically initialized by load_module().  Modules
 * should use the THIS_MODULE macro to retrieve their own module pointer
 * rather than accessing this variable directly.
 */
#ifdef MODULE
# ifndef MODULE_MAIN_FILE
extern
# endif
Module *RENAME_SYMBOL(_this_module);
# ifdef MODULE_MAIN_FILE
Module **_this_module_ptr = &RENAME_SYMBOL(_this_module);       /* used by loader */
# endif
#endif

/*************************************************************************/

/* If the preprocessor symbol MODULE_MAIN_FILE is defined, the following
 * required variable is automatically defined.  This symbol should be
 * defined for one (and only one) file per module.  (Normally, this symbol
 * is defined automatically by modules/Makerules for the main source file
 * for each module, and does not need to be defined manually.)
 */
#if defined(MODULE_MAIN_FILE)
const int32 module_version = MODULE_VERSION_CODE;
#endif

/*************************************************************************/

#endif /* MODULES_H */

/*
 * Local variables:
 *   c-file-style: "stroustrup"
 *   c-file-offsets: ((case-label . *) (statement-case-intro . *))
 *   indent-tabs-mode: nil
 * End:
 *
 * vim: expandtab shiftwidth=4:
 */
Revision:	1209
Committed:	Thu Aug 25 19:05:49 2011 UTC (14 years, 11 months ago) by michael
Content type:	text/x-chdr
File size:	11046 byte(s)
Log Message:	- run everything thru indent "-bli0 -di1 -npcs -nut -cdw -bls -nbbo -bap"
#	User	Rev	Content
1	michael	1194	/* Module support include file (interface definition).
2			*
3			* IRC Services is copyright (c) 1996-2009 Andrew Church.
4			* E-mail: <achurch@achurch.org>
5			* Parts written by Andrew Kempe and others.
6			* This program is free but copyrighted software; see the file GPL.txt for
7			* details.
8			*/
9
10			#ifndef MODULES_H
11			#define MODULES_H
12
13			/*************************************************************************/
14
15			/* Version code macro. Parameters are:
16			* major: Major version number (the "5" in 5.1a0).
17			* minor: Minor version number (the "1" in 5.1a0).
18			* status: Release status (alpha, prerelease, or final). Use one of
19			* the MODULE_VERSION_{ALPHA,PRE,FINAL} macros:
20			* 5.1a0 -> MODULE_VERSION_ALPHA
21			* 5.1pre0 -> MODULE_VERSION_PRE
22			* 5.1.0 -> MODULE_VERSION_FINAL
23			* release: Release number (the "0" in 5.1a0).
24			*/
25			#define MODULE_VERSION(major,minor,status,release) ( \
26			((major) > 5 \|\| ((major) == 5 && (minor) >= 1)) \
27			? ((major)<<24 \| (minor)<<16 \| (status)<<12 \| (release))\
28			: (0x050000 \| (release)) \
29			)
30			#define MODULE_VERSION_ALPHA 0xA
31			#define MODULE_VERSION_PRE 0xB
32			#define MODULE_VERSION_FINAL 0xF
33
34			/* Version code for modules. This will be updated whenever a change to the
35			* program (structures, callbacks, etc.) makes existing binary modules
36			* incompatible. This is stored in the compiled modules and used to let
37			* Services determine whether a given module is compatible with the current
38			* binary; it can also be used with #if to make source code compatible with
39			* multiple versions of Services.
40			*/
41			#define MODULE_VERSION_CODE MODULE_VERSION(5,1,MODULE_VERSION_FINAL,0)
42
43			/*************************************************************************/
44
45			/* Module information. The actual structure is defined in module.c, and is
46			* opaque to the caller. */
47			struct Module_;
48			typedef struct Module_ Module;
49
50			/* Callback function prototype. */
51	michael	1209	typedef int (*callback_t) ();
52	michael	1194
53			/* Callback priority limits. */
54			#define CBPRI_MIN -10000
55			#define CBPRI_MAX 10000
56
57			/*************************************************************************/
58
59			/* Macro to rename a symbol based on the module's ID (MODULE_ID) in order
60			* to avoid symbol clashes. This roundabout construction is necessary to
61			* force the preprocessor to substitute the value of MODULE_ID instead of
62			* appending "MODULE_ID" literally. */
63
64			#define RENAME_SYMBOL(symbol) RENAME_SYMBOL_2(symbol,MODULE_ID)
65			#define RENAME_SYMBOL_2(symbol,id) RENAME_SYMBOL_3(symbol,id)
66			#define RENAME_SYMBOL_3(symbol,id) symbol##_##id
67
68			/*************************************************************************/
69
70			/* Macros to retrieve a pointer to the current module or its name. */
71
72			#ifdef MODULE
73			# define THIS_MODULE RENAME_SYMBOL(_this_module)
74			#else
75			# define THIS_MODULE NULL
76			#endif
77
78			#define MODULE_NAME (get_module_name(THIS_MODULE))
79
80			/*************************************************************************/
81			/*************************************************************************/
82
83			/* External variable/function declarations. Note that many of the
84			* functions below are macroized to automatically pass a "current-module"
85			* parameter; functions whose names begin with "_" should not be called
86			* directly. */
87
88			/*************************************************************************/
89
90			/* Initialization and cleanup: */
91
92			extern int modules_init(int ac, char **av);
93			extern void modules_cleanup(void);
94			extern void unload_all_modules(void);
95
96			/*************************************************************************/
97
98			/* Module-level functions: */
99
100			/* Load a new module and return the Module pointer, or NULL on error. */
101			extern Module load_module(const char modulename);
102
103			/* Remove a module from memory. Return nonzero on success, zero on
104			* failure. */
105	michael	1209	extern int unload_module(Module * module);
106	michael	1194
107			/* Return the Module pointer for the named module, or NULL if no such
108			* module exists. */
109			extern Module find_module(const char modulename);
110
111			/* Increment or decrement the use count for the given module. A module
112			* cannot be unloaded while its use count is nonzero. */
113			#define use_module(mod) _use_module(mod,THIS_MODULE)
114			#define unuse_module(mod) _unuse_module(mod,THIS_MODULE)
115	michael	1209	extern void _use_module(Module * module, const Module * caller);
116			extern void _unuse_module(Module * module, const Module * caller);
117	michael	1194
118			/* Re-read configuration files for all modules. Return nonzero on success,
119			* zero on failure. */
120			int reconfigure_modules(void);
121
122			/*************************************************************************/
123
124			/* Module symbol/information retrieval: */
125
126			/* Retrieve the value of the named symbol in the given module. Return NULL
127			* if no such symbol exists. Note that this function should not be used
128			* for symbols whose value might be NULL, because there is no way to
129			* distinguish a symbol value of NULL from an error return. For such
130			* symbols, or for cases where a symbol might legitimately not exist and
131			* no error should be printed for nonexistence, use check_module_symbol(). */
132			#define get_module_symbol(mod,symname) \
133			_get_module_symbol(mod,symname,THIS_MODULE)
134	michael	1209	extern void _get_module_symbol(Module module, const char *symname,
135			const Module * caller);
136	michael	1194
137			/* Check whether the given symbol exists in the given module; return 1 if
138			* so, 0 otherwise. If `resultptr' is non-NULL and the symbol exists, the
139			* value is stored in the variable it points to. If `errorptr' is non-NULL
140			* and the symbol does not exist, a human-readable error message is stored
141			* in the variable it points to. */
142	michael	1209	extern int check_module_symbol(Module * module, const char *symname,
143	michael	1194	void resultptr, const char errorptr);
144
145			/* Retrieve the name of the given module. */
146	michael	1209	extern const char get_module_name(const Module module);
147	michael	1194
148			/*************************************************************************/
149
150			/* Callback-related functions: (all functions except register_callback()
151			* and call_callback() return nonzero on success and zero on error)
152			*/
153
154			/* Register a new callback list. */
155			#define register_callback(name) _register_callback(THIS_MODULE,name)
156	michael	1209	extern int _register_callback(Module * module, const char *name);
157	michael	1194
158			/* Call all functions in a callback list. Return 1 if a callback returned
159			* nonzero, 0 if all callbacks returned zero, or -1 on error. The _N
160			* formats allow passing parameters. */
161			#define call_callback(id) \
162			call_callback_1(id, NULL)
163			#define call_callback_1(id,arg1) \
164			call_callback_2(id, arg1, NULL)
165			#define call_callback_2(id,arg1,arg2) \
166			call_callback_3(id, arg1, arg2, NULL)
167			#define call_callback_3(id,arg1,arg2,arg3) \
168			call_callback_4(id, arg1, arg2, arg3, NULL)
169			#define call_callback_4(id,arg1,arg2,arg3,arg4) \
170			call_callback_5(id, arg1, arg2, arg3, arg4, NULL)
171			#define call_callback_5(id,arg1,arg2,arg3,arg4,arg5) \
172			_call_callback_5(THIS_MODULE, id, (void *)(long)(arg1), \
173			(void )(long)(arg2), (void )(long)(arg3), \
174			(void )(long)(arg4), (void )(long)(arg5))
175	michael	1209	extern int _call_callback_5(Module * module, int id, void arg1, void arg2,
176	michael	1194	void arg3, void arg4, void *arg5);
177
178			/* Delete a callback list. */
179			#define unregister_callback(name) _unregister_callback(THIS_MODULE,name)
180	michael	1209	extern int _unregister_callback(Module * module, int id);
181	michael	1194
182			/* Add a function to a callback list with the given priority (higher
183			* priority value = called sooner). Callbacks with the same priority are
184			* called in the order they were added. */
185			#define add_callback_pri(module,name,callback,priority) \
186			_add_callback_pri(module,name,callback,priority,THIS_MODULE)
187	michael	1209	int _add_callback_pri(Module * module, const char *name, callback_t callback,
188			int priority, const Module * caller);
189	michael	1194
190			/* Add a function to a callback list with priority 0. */
191			#define add_callback(module,name,callback) \
192			add_callback_pri(module,name,callback,0)
193
194			/* Remove a function from a callback list. */
195			#define remove_callback(module,name,callback) \
196			_remove_callback(module,name,callback,THIS_MODULE)
197	michael	1209	extern int _remove_callback(Module * module, const char *name,
198			callback_t callback, const Module * caller);
199	michael	1194
200			/*************************************************************************/
201			/*************************************************************************/
202
203			/* Module functions: */
204
205			int init_module(void);
206			int exit_module(int shutdown);
207
208			/*************************************************************************/
209
210			/* Macros to declare a symbol to be exported. Only one may be used per
211			* line, and it must be placed at the beginning of the line and be the only
212			* thing on the line (no semicolon at the end). This does not have any
213			* actual effect on compilation, but such lines are extracted to create
214			* module symbol lists. Note that it is not necessary to explicitly list
215			* the init_module, exit_module, and module_config symbols (and in fact,
216			* doing so will cause an error when linking the final executable).
217			*
218			* Also note that typedefs cannot be used here; use struct tags instead.
219			*
220			* Examples:
221			* EXPORT_VAR(const char *,s_NickServ)
222			* EXPORT_ARRAY(some_array)
223			* EXPORT_FUNC(create_akill)
224			*/
225
226			#define EXPORT_VAR(type,symbol)
227			#define EXPORT_ARRAY(symbol)
228			#define EXPORT_FUNC(symbol)
229
230			/*************************************************************************/
231			/*************************************************************************/
232
233			/* Internal-use stuff. */
234
235			/*************************************************************************/
236
237			/* Pointer to the current module. This is defined in each module's main
238			* source file, and automatically initialized by load_module(). Modules
239			* should use the THIS_MODULE macro to retrieve their own module pointer
240			* rather than accessing this variable directly.
241			*/
242			#ifdef MODULE
243			# ifndef MODULE_MAIN_FILE
244			extern
245			# endif
246			Module *RENAME_SYMBOL(_this_module);
247			# ifdef MODULE_MAIN_FILE
248	michael	1209	Module *_this_module_ptr = &RENAME_SYMBOL(_this_module); / used by loader */
249	michael	1194	# endif
250			#endif
251
252			/*************************************************************************/
253
254			/* If the preprocessor symbol MODULE_MAIN_FILE is defined, the following
255			* required variable is automatically defined. This symbol should be
256			* defined for one (and only one) file per module. (Normally, this symbol
257			* is defined automatically by modules/Makerules for the main source file
258			* for each module, and does not need to be defined manually.)
259			*/
260			#if defined(MODULE_MAIN_FILE)
261			const int32 module_version = MODULE_VERSION_CODE;
262			#endif
263
264			/*************************************************************************/
265
266	michael	1209	#endif /* MODULES_H */
267	michael	1194
268			/*
269			* Local variables:
270			* c-file-style: "stroustrup"
271			* c-file-offsets: ((case-label . ) (statement-case-intro . ))
272			* indent-tabs-mode: nil
273			* End:
274			*
275			* vim: expandtab shiftwidth=4:
276			*/