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"
#	Content
1	/* 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	typedef int (*callback_t) ();
52
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	extern int unload_module(Module * module);
106
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	extern void _use_module(Module * module, const Module * caller);
116	extern void _unuse_module(Module * module, const Module * caller);
117
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	extern void _get_module_symbol(Module module, const char *symname,
135	const Module * caller);
136
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	extern int check_module_symbol(Module * module, const char *symname,
143	void resultptr, const char errorptr);
144
145	/* Retrieve the name of the given module. */
146	extern const char get_module_name(const Module module);
147
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	extern int _register_callback(Module * module, const char *name);
157
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	extern int _call_callback_5(Module * module, int id, void arg1, void arg2,
176	void arg3, void arg4, void *arg5);
177
178	/* Delete a callback list. */
179	#define unregister_callback(name) _unregister_callback(THIS_MODULE,name)
180	extern int _unregister_callback(Module * module, int id);
181
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	int _add_callback_pri(Module * module, const char *name, callback_t callback,
188	int priority, const Module * caller);
189
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	extern int _remove_callback(Module * module, const char *name,
198	callback_t callback, const Module * caller);
199
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	Module *_this_module_ptr = &RENAME_SYMBOL(_this_module); / used by loader */
249	# 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	#endif /* MODULES_H */
267
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	*/