1 |
<?xml version="1.0" encoding="ISO-8859-1"?> |
2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11-strict.dtd"> |
3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
4 |
<head> |
5 |
<meta http-equiv="Content-Style-Type" content="text/css"/> |
6 |
<style type="text/css">@import "style.css";</style> |
7 |
<title>IRC Services Technical Reference Manual - 4. Module system</title> |
8 |
</head> |
9 |
|
10 |
<body> |
11 |
<h1 class="title" id="top">IRC Services Technical Reference Manual</h1> |
12 |
|
13 |
<h2 class="section-title">4. The module system</h2> |
14 |
|
15 |
<p class="section-toc"> |
16 |
4-1. <a href="#s1">The module concept</a> |
17 |
<br/>4-2. <a href="#s2">Structure of a module</a> |
18 |
<br/> 4-2-1. <a href="#s2-1">Required symbols</a> |
19 |
<br/> 4-2-2. <a href="#s2-2">Utility macros and functions</a> |
20 |
<br/> 4-2-3. <a href="#s2-3">Dynamic versus static modules</a> |
21 |
<br/>4-3. <a href="#s3">Module management</a> |
22 |
<br/> 4-3-1. <a href="#s3-1">Module loading</a> |
23 |
<br/> 4-3-2. <a href="#s3-2">Module configuration</a> |
24 |
<br/> 4-3-3. <a href="#s3-3">Module unloading</a> |
25 |
<br/> 4-3-4. <a href="#s3-4">Searching for a module</a> |
26 |
<br/> 4-3-5. <a href="#s3-5">Locking a module in memory</a> |
27 |
<br/> 4-3-6. <a href="#s3-6">Global initialization and cleanup</a> |
28 |
<br/>4-4. <a href="#s4">External symbols</a> |
29 |
<br/> 4-4-1. <a href="#s4-1">Exporting symbols</a> |
30 |
<br/> 4-4-2. <a href="#s4-2">Importing symbols</a> |
31 |
<br/>4-5. <a href="#s5">Callbacks</a> |
32 |
<br/> 4-5-1. <a href="#s5-1">Registering callbacks</a> |
33 |
<br/> 4-5-2. <a href="#s5-2">Hooking into callbacks</a> |
34 |
<br/> 4-5-3. <a href="#s5-3">Calling callbacks</a> |
35 |
<br/>4-6. <a href="#s6">Adding a module to Services</a> |
36 |
</p> |
37 |
|
38 |
<p class="backlink"><a href="3.html">Previous section: Communication (socket) handling</a> | |
39 |
<a href="index.html">Table of Contents</a> | |
40 |
<a href="5.html">Next section: IRC server interface</a></p> |
41 |
|
42 |
<!------------------------------------------------------------------------> |
43 |
<hr/> |
44 |
|
45 |
<h3 class="subsection-title" id="s1">4-1. The module concept</h3> |
46 |
|
47 |
<p>The module system was introduced in Services 5.0, partly to allow |
48 |
greater flexibility in configuring Services, partly to simplify the process |
49 |
of extending Services, and partly to help clarify the boundaries between |
50 |
distinct sets of functionality. Rather than merge every conceivable |
51 |
function into a single monolithic program, Services was divided into a |
52 |
comparatively small core and a number of modules which each implemented |
53 |
distinct sets of features. These modules could then be developed |
54 |
separately from the core and from each other, without concern for the |
55 |
effects of changes in other parts of the program.</p> |
56 |
|
57 |
<p>Aside from providing a cleaner program structure, modules make it |
58 |
simpler to implement different variations on a particular feature. A good |
59 |
example of this is the protocol modules (discussed in |
60 |
<a href="5.html">section 5</a>); rather than a complex set of <tt>#if</tt> |
61 |
and <tt>#else</tt> directives to handle differences between IRC server |
62 |
types, a separate protocol module can be written for each type of IRC |
63 |
server; this results in a certain amount of code duplication for similar |
64 |
protocols, but makes the code for each protocol much more maintainable, and |
65 |
allows the code for a single protocol to be changed easily without worrying |
66 |
that it will break processing for other protocols.</p> |
67 |
|
68 |
<p>Modules also make it easier to add new features to Services, whether as |
69 |
part of the Services package or as third-party additions. By connecting to |
70 |
the Services core and standard modules through a set of well-defined |
71 |
callbacks, no changes need to be made to the main source code when the |
72 |
module is updated, and vice versa. The compilation system (see |
73 |
<a href="10.html#s3-2">section 10-3-2</a>) also makes it easy for users to |
74 |
add modules on their own, by simply "dropping in" the source code for the |
75 |
new module; Services will automatically find the module and compile it.</p> |
76 |
|
77 |
<p>Below, <a href="#s2">section 4-2</a> discusses the basic structure of a |
78 |
module, along with other background issues; <a href="#s3">section 4-3</a> |
79 |
discusses how modules are managed, including the details of module loading, |
80 |
configuration, and unloading; <a href="#s4">section 4-4</a> discusses how |
81 |
to make symbols available to other modules and use symbols from other |
82 |
modules; and <a href="#s5">section 4-5</a> covers callbacks.</p> |
83 |
|
84 |
<p class="backlink"><a href="#top">Back to top</a></p> |
85 |
|
86 |
<!------------------------------------------------------------------------> |
87 |
<hr/> |
88 |
|
89 |
<h3 class="subsection-title" id="s2">4-2. Structure of a module</h3> |
90 |
|
91 |
<p>From the viewpoint of the Services core, a module is a single unit of |
92 |
functionality with a known interface. The only direct accesses made to |
93 |
module data are to a limited number of functions and variables (as |
94 |
described in <a href="#s2-1">section 4-2-1</a> below); all other module |
95 |
interactions occur through callbacks, which it is the module's |
96 |
responsibility to install as necessary.</p> |
97 |
|
98 |
<p>A typical module, therefore, will use its initialization routine (one of |
99 |
the directly-accessed functions) to install callback functions, enabling it |
100 |
to respond to events such as messages from the IRC server or connections on |
101 |
a socket. After performing any other necessary setup actions, the |
102 |
initialization routine returns control to the Services core, which will |
103 |
then call the module's callback functions as appropriate. The bulk of a |
104 |
module is thus usually contained in these callback functions or their |
105 |
helper routines.</p> |
106 |
|
107 |
<p class="backlink"><a href="#top">Back to top</a></p> |
108 |
|
109 |
|
110 |
<h4 class="subsubsection-title" id="s2-1">4-2-1. Required and optional symbols</h4> |
111 |
|
112 |
<p>Modules are required to define two variables, used by the module loader: |
113 |
<b><tt>int32 module_version</tt></b>, initialized to the value |
114 |
of the macro <tt>MODULE_VERSION_CODE</tt>, and |
115 |
<b><tt>Module **_this_module_ptr</tt></b>, a pointer to a variable |
116 |
which will receive the module's handle (see <a href="#s3">section 4-3</a> |
117 |
for information on module handles). However, both of these variables are |
118 |
normally defined by <tt>modules.h</tt> when compiling the module's main |
119 |
file (the source file with the same base name as the module object file), |
120 |
so ordinarily there is no need to be concerned about these variables.</p> |
121 |
|
122 |
<p>Modules may optionally define two functions, which the module loader |
123 |
will call when the module is loaded and unloaded, respectively:</p> |
124 |
|
125 |
<dl> |
126 |
<dt><tt>int <b>init_module</b>()</tt></dt> |
127 |
<dd>Performs any initialization operations necessary for the module, |
128 |
returning nonzero on success, zero on failure. This function is |
129 |
called during the module loading process (see |
130 |
<a href="#s3-1">section 4-3-1</a>); if it returns failure, the |
131 |
module load is aborted.</dd> |
132 |
|
133 |
<dt><tt>int <b>exit_module</b>(int <i>shutdown</i>)</tt></dt> |
134 |
<dd>Performs any cleanup operations necessary for the module. If |
135 |
<tt><i>shutdown</i></tt> is zero, then the function is being called |
136 |
for an unload operation during normal program processing; if |
137 |
<tt>exit_module()</tt> returns zero, then the unload is aborted (a |
138 |
nonzero return value indicates permission to unload the module). |
139 |
If <tt><i>shutdown</i></tt> is nonzero, then the function is being |
140 |
called because the program is shutting down; in this case, the |
141 |
function must perform all necessary shutdown operations (returning |
142 |
zero to cancel the unload is not permitted). <i>Implementation |
143 |
note: The <tt><i>shutdown</i></tt> parameter was included primarily |
144 |
for the protocol modules, due to some shortcuts taken on the |
145 |
assumption that only one protocol module would be used during any |
146 |
given execution.</i></dd> |
147 |
</dl> |
148 |
|
149 |
<p>Modules may also optionally define |
150 |
<b><tt>ConfigDirective module_config[]</tt></b> (this must be an |
151 |
array, not a pointer), containing configuration information for the module |
152 |
which will be processed by the module loader. The use of this array is |
153 |
described in <a href="#s3-2">section 4-3-2</a>.</p> |
154 |
|
155 |
<p class="backlink"><a href="#top">Back to top</a></p> |
156 |
|
157 |
|
158 |
<h4 class="subsubsection-title" id="s2-2">4-2-2. Utility macros and functions</h4> |
159 |
|
160 |
<p>The header file <tt>modules.h</tt>, which must be included by all module |
161 |
source files, includes a few macros for convenience in writing modules:</p> |
162 |
|
163 |
<dl> |
164 |
<dt><tt><b>THIS_MODULE</b></tt></dt> |
165 |
<dd>Evaluates to the module handle for this module. This can be used, |
166 |
for example, if a module wants to pass its handle explicitly to |
167 |
another module, but it is more commonly used by other macros in |
168 |
<tt>modules.h</tt> to automatically pass the module's handle to |
169 |
various module-related routines (see below).</dd> |
170 |
|
171 |
<dt><tt><b>MODULE_NAME</b></tt></dt> |
172 |
<dd>Evaluates to a string containing the module's name; the value |
173 |
should be treated as constant but not literal. (Internally, it is |
174 |
simply the result of <tt>get_module_name(THIS_MODULE)</tt>.)</dd> |
175 |
|
176 |
<dt><tt><b>MODULE_VERSION_CODE</b></tt></dt> |
177 |
<dd>Evaluates to a numeric code indicating the Services version number. |
178 |
The version number consists of four parts: major version number, |
179 |
minor version number, release status (alpha, beta/prerelease, or |
180 |
final), and release number. These are passed to the macro to |
181 |
produce a number indicating the version, where greater values |
182 |
indicate later versions. For example: |
183 |
<div class="code"> MODULE_VERSION_CODE(5,0,MODULE_VERSION_FINAL,4) |
184 |
< MODULE_VERSION_CODE(5,1,MODULE_VERSION_ALPHA,3) |
185 |
< MODULE_VERSION_CODE(5,1,MODULE_VERSION_BETA,2) |
186 |
< MODULE_VERSION_CODE(5,1,MODULE_VERSION_FINAL,1)</div> |
187 |
because version 5.0 is earlier than version 5.1, alpha releases |
188 |
are earlier than beta releases, and beta releases are earlier than |
189 |
final releases. (These values correspond to the versions 5.0.4, |
190 |
5.1a3, 5.1pre2, and 5.1.1 respectively.) While this value is |
191 |
primarily used to set the <tt>module_version</tt> required |
192 |
variable, as described above, it can also be used in conditional |
193 |
compilation when compatibility with multiple versions of Services |
194 |
is desired.</dd> |
195 |
</dl> |
196 |
|
197 |
<p>In addition, many of the routines described in this section take a |
198 |
<tt><i>module</i></tt> or <tt><i>caller</i></tt> parameter, so that the |
199 |
module subsystem knows which module is making the call; however, macros are |
200 |
used to hide this parameter from the module source code, both to improve |
201 |
readability of the code and to avoid potential errors from passing the |
202 |
wrong parameter. These functions are:</p> |
203 |
<ul> |
204 |
<li><tt>add_callback()</tt> (and <tt>add_callback_pri()</tt>)</li> |
205 |
<li><tt>call_callback()</tt> (and variations)</li> |
206 |
<li><tt>module_log()</tt> (and variations; declared in <tt>log.h</tt>)</li> |
207 |
<li><tt>register_callback()</tt></li> |
208 |
<li><tt>remove_callback()</tt></li> |
209 |
<li><tt>unregister_callback()</tt></li> |
210 |
<li><tt>unuse_module()</tt></li> |
211 |
<li><tt>use_module()</tt></li> |
212 |
</ul> |
213 |
|
214 |
<p class="backlink"><a href="#top">Back to top</a></p> |
215 |
|
216 |
|
217 |
<h4 class="subsubsection-title" id="s2-3">4-2-3. Dynamic versus static modules</h4> |
218 |
|
219 |
<p>It is possible for modules to be compiled either <i>dynamically</i>, so |
220 |
that the module is loaded into memory only when used, or <i>statically</i>, |
221 |
building all modules into the main executable file. The decision of which |
222 |
to use is made by the user via the <tt>configure</tt> script, and cannot be |
223 |
controlled by individual modules. In general, modules will behave exactly |
224 |
the same whether compiled dynamically or statically; however, it is |
225 |
important to be aware of particular behaviors with each method, to avoid |
226 |
problems that cause the module to fail when using one method or the other.</p> |
227 |
|
228 |
<p><i>Dynamic linking</i> involves compiling each module into an |
229 |
independent loadable object file, which is then loaded into memory as |
230 |
needed using the system's <tt>dlopen()</tt> family of functions. (If |
231 |
these functions are not available, dynamic modules cannot be used; the |
232 |
<tt>configure</tt> script will detect this and select static modules |
233 |
automatically.) Any direct references to symbols not defined in the |
234 |
module, such as core Services routines, will be marked as unresolved |
235 |
references in the object file. As a result, it is possible to compile a |
236 |
module that references a nonexistent symbol—for example, accidentally |
237 |
typing <tt>str<b>mc</b>p</tt> instead of <tt>str<b>cm</b>p</tt>—and |
238 |
the error will not be detected until an attempt is made to load the module.</p> |
239 |
|
240 |
<p><i>Static linking</i>, on the other hand, results in every module being |
241 |
linked together with the core code to produce a single executable file. |
242 |
This means that every symbol in the Services core—and in other |
243 |
modules—will be available for use. Static linking can detect |
244 |
references to nonexistent symbols at compile time, unlike dynamic linking, |
245 |
but will not generate an error if one module references a symbol from |
246 |
another. For example, if a protocol module erroneously references a symbol |
247 |
from one of the pseudoclients directly (rather than using the symbol lookup |
248 |
method described in <a href="#s4-2">section 4-4-2</a>), the protocol module |
249 |
will fail to load when using dynamic linking unless the appropriate |
250 |
pseudoclient module is loaded first. (Since the current design of Services |
251 |
requires that a protocol module be loaded first, this would result in |
252 |
Services not being able to run at all.)</p> |
253 |
|
254 |
<p>When using modules composed of two or more source files that share |
255 |
internal-use symbols, static linking can cause spurious errors at link |
256 |
time. This is because, even though the symbols are only used internally, |
257 |
they are still included in the final object file for the module; thus, if |
258 |
two separate modules happen to use the same name for a function or |
259 |
variable, the final link will report a "duplicate symbol" error. This is |
260 |
an actual problem with the NickServ and ChanServ modules, both of which |
261 |
include various internal utility routines in a separate source file, and as |
262 |
a result some ChanServ routines have to be renamed (see |
263 |
<a href="7.html#s4-1-1-rename">the relevant part of section 7-4-1-1</a>).</p> |
264 |
|
265 |
<p>Additionally, when using static linking, module-global variables will |
266 |
always retain their values between a module unload and a subsequent module |
267 |
load; when using dynamic linking, it is system-dependent whether the values |
268 |
will be retained or reset to their initial values. Thus it is important |
269 |
that a module's cleanup routine not only free all resources used by the |
270 |
module, but also reset all variables to appropriate values for the next |
271 |
call to the initialization routine.</p> |
272 |
|
273 |
<p>For these reasons, it is best to test modules using both dynamic and |
274 |
static linking, to ensure that unintended errors are not introduced.</p> |
275 |
|
276 |
|
277 |
<p class="backlink"><a href="#top">Back to top</a></p> |
278 |
|
279 |
<!------------------------------------------------------------------------> |
280 |
<hr/> |
281 |
|
282 |
<h3 class="subsection-title" id="s3">4-3. Module management</h3> |
283 |
|
284 |
<p>The module subsystem uses the routines described in this section to |
285 |
manage modules, performing loading, configuration and unloading as well as |
286 |
checking whether a module is loaded or locking modules into memory.</p> |
287 |
|
288 |
<p>Most module subsystem routines take or return a <i>module handle</i>, a |
289 |
value of type <tt>Module *</tt>, to identify a particular module. The |
290 |
<tt>Module</tt> type is declared as simply <tt>struct Module_</tt> in |
291 |
<tt>modules.h</tt>, rendering the type opaque to callers. Internally, |
292 |
<tt>struct Module_</tt> is used to hold information about each loaded |
293 |
module, and has the following fields:</p> |
294 |
|
295 |
<dl> |
296 |
<dt><tt>Module *<b>next</b>, *<b>prev</b></tt></dt> |
297 |
<dd>Used to maintain the linked list of loaded modules.</dd> |
298 |
|
299 |
<dt><tt>char *<b>name</b></tt></dt> |
300 |
<dd>The module's name, set to the pathname used to load the module (for |
301 |
example, "<tt>nickserv/main</tt>").</dd> |
302 |
|
303 |
<dt><tt>ConfigDirective *<b>modconfig</b></tt></dt> |
304 |
<dd>The value of the symbol <tt>module_config</tt> in this module, or |
305 |
<tt>NULL</tt> if the <tt>module_config</tt> symbol does not exist.</dd> |
306 |
|
307 |
<dt><tt>Module ***<b>this_module_pptr</b></tt></dt> |
308 |
<dd>The value of the symbol <tt>_this_module_ptr</tt> in this module. |
309 |
(This is the <i>address</i> of the <tt>_this_module_ptr</tt> |
310 |
variable, which itself is a pointer to a variable of type |
311 |
<tt>Module *</tt>, so the type of this field is |
312 |
<tt>Module ***</tt>.)</dd> |
313 |
|
314 |
<dt><tt>const int32 *<b>module_version_ptr</b></tt></dt> |
315 |
<dd>The value of the symbol <tt>module_version</tt> in this module |
316 |
(again, the address of the variable, not its value).</dd> |
317 |
|
318 |
<dt><tt>void *<b>dllhandle</b></tt></dt> |
319 |
<dd>The handle returned by the system <tt>dlopen()</tt> function. For |
320 |
static linking, this instead points to an internal structure with |
321 |
the module data.</dd> |
322 |
|
323 |
<dt><tt>CallbackList *<b>callbacks</b></tt> |
324 |
<br/><tt>int <b>callbacks_count</b></tt></dt> |
325 |
<dd>A variable-length array containing the callbacks registered by this |
326 |
module.</dd> |
327 |
|
328 |
<dt><tt>const Module **<b>users</b></tt> |
329 |
<br/><tt>int <b>users_count</b></tt></dt> |
330 |
<dd>A variable-length array containing handles of modules which have |
331 |
called <tt>use_module()</tt> for this module.</dd> |
332 |
</dl> |
333 |
|
334 |
<p>Loaded modules are kept as a doubly-linked list, with the list head in |
335 |
the file-scope variable <tt>modulelist</tt>. This list always contains at |
336 |
least one entry: a dummy entry for the Services core, defined in the |
337 |
variable <tt>coremodule</tt>.</p> |
338 |
|
339 |
<p>The module management routines are:</p> |
340 |
|
341 |
<dl> |
342 |
<dt><tt>Module *<b>load_module</b>(const char *<i>modulename</i>)</tt></dt> |
343 |
<dd>Loads the given module and returns a pointer to its module handle, |
344 |
or <tt>NULL</tt> on failure. Described in <a href="#s3-1">section |
345 |
4-3-1</a>.</dd> |
346 |
|
347 |
<dt><tt>int <b>unload_module</b>(Module *<i>module</i>)</tt></dt> |
348 |
<dd>Unloads the given module. Returns nonzero if the module was |
349 |
successfully unloaded, zero if not. Described in |
350 |
<a href="#s3-3">section 4-3-3</a>.</dd> |
351 |
|
352 |
<dt><tt>Module *<b>find_module</b>(const char *<i>modulename</i>)</tt></dt> |
353 |
<dd>Returns a handle for the module whose name is given by |
354 |
<tt><i>modulename</i></tt>. If no such module has been loaded, |
355 |
returns <tt>NULL</tt>. Described in <a href="#s3-4">section |
356 |
4-3-4</a>.</dd> |
357 |
|
358 |
<dt><tt>void <b>use_module</b>(Module *<i>module</i>)</tt></dt> |
359 |
<dd>Marks the given module as "in use", preventing it from being |
360 |
unloaded. Described in <a href="#s3-5">section 4-3-5</a>.</dd> |
361 |
|
362 |
<dt><tt>void <b>unuse_module</b>(Module *<i>module</i>)</tt></dt> |
363 |
<dd>Releases the lock on a module set by <tt>use_module()</tt>. |
364 |
Described in <a href="#s3-5">section 4-3-5</a>.</dd> |
365 |
|
366 |
<dt><tt>void <b>modules_init</b>()</tt></dt> |
367 |
<dd>Initializes the module subsystem. Described in |
368 |
<a href="#s3-6">section 4-3-6</a>.</dd> |
369 |
|
370 |
<dt><tt>void <b>modules_cleanup</b>()</tt></dt> |
371 |
<dd>Shuts down the module subsystem. Described in |
372 |
<a href="#s3-6">section 4-3-6</a>.</dd> |
373 |
</dl> |
374 |
|
375 |
<p class="backlink"><a href="#top">Back to top</a></p> |
376 |
|
377 |
|
378 |
<h4 class="subsubsection-title" id="s3-1">4-3-1. Module loading</h4> |
379 |
|
380 |
<p>A module can be loaded by calling the <tt>load_module()</tt> routine. |
381 |
This routine takes a single parameter, a string giving the name of the |
382 |
module to load (such as "nickserv/main"), and returns the handle for the |
383 |
newly-loaded module or <tt>NULL</tt> on failure. The routine:</p> |
384 |
|
385 |
<ul> |
386 |
<li class="spaced">Calls <tt>internal_load_module()</tt> to load the module |
387 |
into memory. This helper routine takes care of performing the |
388 |
actual module load (or lookup, when modules are linked statically) |
389 |
and filling in the <tt>Module</tt> structure; see below for |
390 |
details.</li> |
391 |
|
392 |
<li class="spaced">Links the new <tt>Module</tt> structure into the loaded |
393 |
module list.</li> |
394 |
|
395 |
<li class="spaced">Calls the core's <tt>configure()</tt> routine to |
396 |
configure module settings; see <a href="#s3-2">section 4-3-2</a> |
397 |
for details.</li> |
398 |
|
399 |
<li class="spaced">Calls <tt>internal_init_module()</tt> to perform module |
400 |
initialization. This returns nonzero (success) if the module's |
401 |
initialization function, <tt>module_init()</tt>, returns success |
402 |
(or does not exist).</li> |
403 |
|
404 |
<li class="spaced">Calls the "<tt>load module</tt>" callback, a module |
405 |
callback (see <a href="#s5">section 4-5</a>) used to signal that a |
406 |
new module has been loaded.</li> |
407 |
|
408 |
<li class="spaced">Finally, performs a check to ensure that a valid |
409 |
protocol module is loaded. This is a kludge to ensure that a |
410 |
protocol module is loaded before any other modules, since some |
411 |
modules alter their initialization behavior depending on the |
412 |
protocol in use. See also <a href="5.html#s1">section 5-1</a>.</li> |
413 |
</ul> |
414 |
|
415 |
<p>The actual low-level work of loading the module and initializing the |
416 |
<tt>Module</tt> structure is handled by the <tt>internal_load_module()</tt> |
417 |
helper routine mentioned above. This routine:</p> |
418 |
|
419 |
<ul> |
420 |
<li class="spaced">Ensures that the name given (which, when using dynamic |
421 |
linking, becomes part of the file pathname) does not contain |
422 |
<tt>../</tt>", to avoid attempts by malicious code to access files |
423 |
outside the Services data directory.</li> |
424 |
|
425 |
<li class="spaced">Checks whether the module has already been loaded, |
426 |
returning an error if so.</li> |
427 |
|
428 |
<li class="spaced">Calls <tt>my_dlopen()</tt> (see below) to actually load |
429 |
the module into memory.</li> |
430 |
|
431 |
<li class="spaced">Allocates a new <tt>Module</tt> structure, filling in |
432 |
the system module handle and module name.</li> |
433 |
|
434 |
<li class="spaced">Looks up the <tt>_this_module_ptr</tt> symbol in the |
435 |
module, returning an error if the symbol is not found, and stores |
436 |
the symbol's value in the <tt>this_module_pptr</tt> field of the |
437 |
<tt>Module</tt> structure. The variable pointed to by |
438 |
<tt>_this_module_ptr</tt> is then set to the module handle, |
439 |
allowing the <tt>THIS_MODULE</tt> macro to work. |
440 |
|
441 |
<p>To perform the lookup, <tt>internal_load_module()</tt> first |
442 |
calls <tt>check_module_symbol()</tt> to get the symbol value. |
443 |
Then, if dynamic linking is in use, the returned value is checked |
444 |
the <tt>this_module_pptr</tt> field of each module in the loaded |
445 |
module list to see whether the same address has been used for a |
446 |
different module. This latter check is required because of a |
447 |
problem (on some systems) with the system function |
448 |
<tt>dlsym()</tt>, used for looking up symbols when dynamic linking |
449 |
is in use: if the requested symbol is not present in the requested |
450 |
module but is present in another module, <tt>dlsym()</tt> may |
451 |
return the symbol from the other module (see <a href="#s4-2">section |
452 |
4-4-2</a> for details).</p> |
453 |
|
454 |
<p>Note that the implementation used with static linking does not |
455 |
have this problem, rendering the check unnecessary. In fact, |
456 |
attempting to perform the check with static linking can actually |
457 |
cause problems on some systems. This is due to constant merging |
458 |
performed by linkers, which results in distinct modules |
459 |
legitimately having the same value for such a symbol. This has |
460 |
been observed with the <tt>module_version</tt> symbol (see below), |
461 |
so the check is disabled when static linking is in use.</p></li> |
462 |
|
463 |
<li class="spaced">Looks up the <tt>module_version</tt> symbol in the |
464 |
module, returning an error if the symbol is not found or the 32-bit |
465 |
value that it points to does not match the value of the |
466 |
<tt>MODULE_VERSION_CODE</tt> macro, and stores the symbol value |
467 |
(variable address) in the <tt>module_version_ptr</tt> field of the |
468 |
<tt>Module</tt> structure.</li> |
469 |
|
470 |
<li class="spaced">Looks up the <tt>module_config</tt> symbol in the |
471 |
module, setting the <tt>modconfig</tt> field of the <tt>Module</tt> |
472 |
structure to the symbol's value (or <tt>NULL</tt> if the symbol is |
473 |
not found).</li> |
474 |
|
475 |
<li class="spaced">Returns the new <tt>Module</tt> structure.</li> |
476 |
</ul> |
477 |
|
478 |
<p>The <tt>my_dlopen()</tt> function referred to above is one of four |
479 |
wrappers for the system dynamic linking functions: <tt>dlopen()</tt>, |
480 |
<tt>dlclose()</tt>, <tt>dlsym()</tt>, and <tt>dlerror()</tt>. When using |
481 |
dynamic linking, the wrapper functions essentially just call their system |
482 |
counterparts, although <tt>my_dlopen()</tt> generates the actual pathname |
483 |
from the module name (prepending the module directory pathname and |
484 |
appending the shared object extension "<tt>.so</tt>"), and |
485 |
<tt>my_dlsym()</tt> includes workarounds for systems that prepend symbol |
486 |
names with underscores and that do not handle <tt>dlsym(NULL,...)</tt>. |
487 |
When static linking is in use, the wrapper functions instead search through |
488 |
the pregenerated module and symbol lists for the requested module or symbol |
489 |
(<tt>dlclose()</tt> does nothing, and <tt>dlerror()</tt> uses a static |
490 |
error message variable to hold the value to return). See |
491 |
<a href="10.html#s3-2">section 10-3-2</a>) for details on the generation of |
492 |
these lists.</p> |
493 |
|
494 |
<p>Note that <tt>load_module()</tt> (and its counterpart, |
495 |
<tt>unload_module()</tt>) are only intended to be called by the Services |
496 |
core to load modules specified by <tt>LoadModule</tt> directives in |
497 |
<tt>ircservices.conf</tt>. Modules should never attempt to load other |
498 |
modules on their own, since the user may have intentionally chosen not to |
499 |
load certain modules; instead, an error should be generated if a required |
500 |
module is not available.</p> |
501 |
|
502 |
<p class="backlink"><a href="#top">Back to top</a></p> |
503 |
|
504 |
|
505 |
<h4 class="subsubsection-title" id="s3-2">4-3-2. Module configuration</h4> |
506 |
|
507 |
<p>Configuration of modules is performed through the same routine, |
508 |
<tt>configure()</tt>, that handles the Services core configuration; |
509 |
however, a different file is used, <tt>modules.conf</tt> rather than |
510 |
<tt>ircservices.conf</tt>, and each module's configuration directives must |
511 |
be enclosed by the <tt>Module</tt> and <tt>EndModule</tt> meta-directives. |
512 |
(Configuration files and the <tt>configure()</tt> routine are described in |
513 |
detail in <a href="2.html#s3-2">section 2-3-2</a>.)</p> |
514 |
|
515 |
<p>Each module can define configuration directives to be parsed by the |
516 |
configuration file reader by creating an array of <tt>ConfigDirective</tt> |
517 |
entries named <tt>module_config</tt>. <tt>load_module()</tt> will check |
518 |
for this symbol and, if found, pass it to <tt>configure()</tt>, as |
519 |
described above; thus, the variables corresponding to the configuration |
520 |
directives will have already been set when the module's |
521 |
<tt>init_module()</tt> function is called. The directives will likewise be |
522 |
reprocessed automatically during reconfiguration; however, it may be |
523 |
necessary for the module to detect changes in configuration variables (such |
524 |
as the nickname of a pseudoclient). For this purpose, the module can hook |
525 |
into the "<tt>reconfigure</tt>" callback, which is called once before |
526 |
reconfiguration takes place and once after (see |
527 |
<a href="c.html#s2">appendix C</a> for details on the callback).</p> |
528 |
|
529 |
<p>All configuration variables will be reset to their initial values when |
530 |
the module is unloaded, so the module's <tt>exit_module()</tt> routine does |
531 |
not need to take any particular actions with respect to such variables.</p> |
532 |
|
533 |
<p class="backlink"><a href="#top">Back to top</a></p> |
534 |
|
535 |
|
536 |
<h4 class="subsubsection-title" id="s3-3">4-3-3. Module unloading</h4> |
537 |
|
538 |
<p>Loaded modules are unloaded from memory with the <tt>unload_module()</tt> |
539 |
routine. This routine, which is implemented in a separate |
540 |
<tt>internal_unload_module()</tt> routine to allow passing a |
541 |
<tt><i>shutdown</i></tt> parameter to the module's cleanup function, |
542 |
performs the reverse of <tt>load_module()</tt>'s operations, returning |
543 |
nonzero if the module is successfully unloaded, zero if not. The routine:</p> |
544 |
|
545 |
<ul> |
546 |
<li class="spaced">Checks whether the module is in use (locked) by another |
547 |
module (see <a href="#s3-5">section 4-3-5</a>), returning failure |
548 |
if so.</li> |
549 |
|
550 |
<li class="spaced">Calls the module's <tt>exit_module()</tt> function (if |
551 |
it exists) with a parameter of zero, indicating that the unload |
552 |
request is explicit rather than part of the program shutdown |
553 |
process. The unload fails if the function returns zero |
554 |
(failure).</li> |
555 |
|
556 |
<li class="spaced">Removes the module from the global module list, ensuring |
557 |
that other modules cannot access it during the unload procedure |
558 |
(particularly when the "<tt>unload module</tt>" callback is |
559 |
called).</li> |
560 |
|
561 |
<li class="spaced">Checks that the module has not left any other modules in |
562 |
a locked state, by calling <tt>use_module()</tt> without a |
563 |
corresponding <tt>unuse_module()</tt> (see <a href="#s3-5">section |
564 |
4-3-5</a>). If it has, a warning message is logged and the |
565 |
offending locks are removed.</li> |
566 |
|
567 |
<li class="spaced">Checks that the module has not left any callback |
568 |
functions hooked into other modules' (or the core's) callbacks. If |
569 |
it has, a warning message is logged and the offending functions are |
570 |
removed.</li> |
571 |
|
572 |
<li class="spaced">Checks that the module has not left any callbacks of its |
573 |
own registered. If it has, a warning message is logged and the |
574 |
offending callbacks are removed.</li> |
575 |
|
576 |
<li class="spaced">Calls the "<tt>unload module</tt>" callback, passing the |
577 |
handle for the module that is being unloaded.</li> |
578 |
|
579 |
<li class="spaced">Calls <tt>deconfigure()</tt> for the module's |
580 |
configuration directives (if any), restoring configuration |
581 |
variables to their original values.</li> |
582 |
|
583 |
<li class="spaced">Frees resources used by the <tt>Module</tt> structure, |
584 |
and calls <tt>my_dlclose()</tt> to unload the module at the system |
585 |
level.</li> |
586 |
</ul> |
587 |
|
588 |
<p>Aside from <tt>unload_module()</tt>, modules are also unloaded during |
589 |
the shutdown process (see <a href="#s3-6">section 4-3-6</a>).</p> |
590 |
|
591 |
<p class="backlink"><a href="#top">Back to top</a></p> |
592 |
|
593 |
|
594 |
<h4 class="subsubsection-title" id="s3-4">4-3-4. Searching for a module</h4> |
595 |
|
596 |
<p>If one module needs to access another, it can do so with the |
597 |
<tt>find_module()</tt> routine. This routine takes a module name as |
598 |
parameter, searches through the loaded module list for a module whose name |
599 |
exactly matches the given name (case-sensitively), and returns the handle |
600 |
for that module (<tt>NULL</tt> if no matching module is found).</p> |
601 |
|
602 |
<p><tt>find_module()</tt> is used most commonly when one module wants to |
603 |
use functionality provided by another; for example, the module implementing |
604 |
the ChanServ pseudoclient (<tt>chanserv/main</tt>) uses it to retrieve the |
605 |
handle for the NickServ module (<tt>nickserv/main</tt>). Note, however, |
606 |
that in cases where the module being searched for is not required, it may |
607 |
not be present at initialization time; in this case, it is better to hook |
608 |
into the core's "<tt>load module</tt>" and "<tt>unload module</tt>" |
609 |
callbacks, and only use <tt>find_module()</tt> to check whether the desired |
610 |
module has already been loaded when <tt>init_module()</tt> is called. For |
611 |
example, the MemoServ module, <tt>memoserv/main</tt>, takes this approach |
612 |
with respect to the <tt>chanserv/main</tt> module when deciding whether to |
613 |
enable channel memos.</p> |
614 |
|
615 |
<p class="backlink"><a href="#top">Back to top</a></p> |
616 |
|
617 |
|
618 |
<h4 class="subsubsection-title" id="s3-5">4-3-5. Locking a module in memory</h4> |
619 |
|
620 |
<p>If one module requires another in order to function properly, the |
621 |
"user" module can request that the "used" module not be unloaded. This is |
622 |
accomplished by calling the <tt>use_module()</tt> routine, passing the |
623 |
"used" module as the <tt><i>module</i></tt> parameter; this causes the |
624 |
specified module to be locked in memory. When the module is no longer |
625 |
needed (for example, when the "user" module's <tt>exit_module()</tt> |
626 |
routine is being called for unloading), <tt>unuse_module()</tt> unlocks the |
627 |
module, allowing it to be unloaded normally.</p> |
628 |
|
629 |
<p>One problem that can arise when locking resources is the case of a |
630 |
circular lock dependency: if module A has locked module B, but module B has |
631 |
also locked module A, then neither of them can be unloaded until one or the |
632 |
other module releases its lock; if the modules only release their locks at |
633 |
cleanup time, there would be no way to unload them. In order to prevent |
634 |
situations like this, <tt>use_module()</tt> checks for such circular |
635 |
dependencies and issues a warning if one is detected (in the form of a |
636 |
"BUG" message written to the log file). Naturally, it is also not |
637 |
permitted for a module to attempt to lock itself.</p> |
638 |
|
639 |
<p>Note that both of these routines are internally named with a preceding |
640 |
underscore (<tt>_use_module()</tt>, <tt>_unuse_module()</tt>) and take a |
641 |
second parameter, <tt>const Module *<i>caller</i></tt>, which is used to |
642 |
ensure that modules do not leave stale locks around when they are unloaded |
643 |
(as described in <a href="#s3-3">section 4-3-3</a>). However, these are |
644 |
hidden by macros which automatically pass <tt>THIS_MODULE</tt> as the |
645 |
<tt><i>caller</i></tt> parameter.</p> |
646 |
|
647 |
<p class="backlink"><a href="#top">Back to top</a></p> |
648 |
|
649 |
|
650 |
<h4 class="subsubsection-title" id="s3-6">4-3-6. Global initialization and cleanup</h4> |
651 |
|
652 |
<p>Before calling any module-related routines, the module subsystem must be |
653 |
initialized by calling <tt>modules_init()</tt>, which obtains the system |
654 |
handle for the program itself (when using dynamic linking) and sets up the |
655 |
three module subsystem callbacks: "<tt>load module</tt>", |
656 |
"<tt>reconfigure</tt>", and "<tt>unload module</tt>".</p> |
657 |
|
658 |
<p>Likewise, the <tt>modules_cleanup()</tt> routine must be called when the |
659 |
program shuts down. Aside from removing the callbacks mentioned above, |
660 |
<tt>modules_cleanup()</tt> checks that other parts of the Services core |
661 |
have removed any callbacks they registered, and calls the internal routine |
662 |
<tt>unload_all_modules()</tt> to walk the loaded module list and unload |
663 |
each module. In this case, each module's <tt>exit_module()</tt> function |
664 |
is called with a nonzero <tt><i>shutdown</i></tt> value, indicating that |
665 |
the program is shutting down and the module must clean up after itself. |
666 |
(The module will be unloaded regardless of the return value of |
667 |
<tt>exit_module()</tt>.)</p> |
668 |
|
669 |
<p class="backlink"><a href="#top">Back to top</a></p> |
670 |
|
671 |
<!------------------------------------------------------------------------> |
672 |
<hr/> |
673 |
|
674 |
<h3 class="subsection-title" id="s4">4-4. External symbols</h3> |
675 |
|
676 |
<p>While some modules only require Services core functions to operate, most |
677 |
interact with other modules. This necessitates a way of accessing |
678 |
functions and data provided by outside modules.</p> |
679 |
|
680 |
<p class="backlink"><a href="#top">Back to top</a></p> |
681 |
|
682 |
|
683 |
<h4 class="subsubsection-title" id="s4-1">4-4-1. Exporting symbols</h4> |
684 |
|
685 |
<p>A module can designate certain symbols (functions or variables) to be |
686 |
exported, so that other modules can access them as described in the next |
687 |
section. This is done using one of three macros, depending on what is |
688 |
being exported:</p> |
689 |
|
690 |
<ul> |
691 |
<li><b><tt>EXPORT_FUNC(<i>symbol</i>)</tt></b> (for functions)</li> |
692 |
<li><b><tt>EXPORT_VAR(<i>type</i>,<i>symbol</i>)</tt></b> (for ordinary |
693 |
variables)</li> |
694 |
<li><b><tt>EXPORT_ARRAY(<i>eltype</i>,<i>symbol</i>)</tt></b> (for arrays; |
695 |
<tt><i>eltype</i></tt> is the type of an element of the array)</li> |
696 |
</ul> |
697 |
|
698 |
<p>These macros do not expand to anything themselves, but are used by the |
699 |
compilation process (see <a href="10.html#s3-2">section 10-3-2</a>) to |
700 |
generate lists of exported symbols when using static linking. Even without |
701 |
these macros, the symbols will still (if not declared <tt>static</tt>) be |
702 |
recorded in the object file, but since there is no way to access the |
703 |
program's symbols when using static linking—and in fact, the symbols |
704 |
may have been stripped from the executable file by the user—the |
705 |
macros must be used in order for <tt>get_module_symbol()</tt> (see |
706 |
<a href="#s4-2">section 4-4-2</a> below) to be able to retrieve the |
707 |
symbol's value.</p> |
708 |
|
709 |
<p>Note that the symbols used by the module subsystem |
710 |
(<tt>module_version</tt> and so on, as described in <a href="#s2-1">section |
711 |
4-2-1</a>) are automatically made available to the module subsystem, and |
712 |
need not be explicitly exported. This is done by the <tt>Makefile</tt> |
713 |
controlling module compilation, as described in |
714 |
<a href="10.html#s3-2">section 10-3-2</a>.</p> |
715 |
|
716 |
<p class="backlink"><a href="#top">Back to top</a></p> |
717 |
|
718 |
|
719 |
<h4 class="subsubsection-title" id="s4-2">4-4-2. Importing symbols</h4> |
720 |
|
721 |
<p>There are two methods of accessing symbols located in other modules: by |
722 |
calling <tt>get_module_symbol()</tt> or <tt>check_module_symbol()</tt>, or |
723 |
by referencing the symbol directly. Each has its benefits and |
724 |
disadvantages.</p> |
725 |
|
726 |
<p><tt>get_module_symbol()</tt> and <tt>check_module_symbol()</tt> allow a |
727 |
caller to retrieve the value of a given symbol in a specified (or any) |
728 |
module. The functions are declared as follows (note that |
729 |
<tt>get_module_symbol()</tt> is declared internally as |
730 |
<tt>_get_module_symbol()</tt> and takes a hidden <tt><i>caller</i></tt> |
731 |
parameter, but these are hidden by a macro in <tt>modules.h</tt>):</p> |
732 |
|
733 |
<div class="code">void *<b>get_module_symbol</b>(Module *<i>module</i>, |
734 |
const char *<i>symname</i>) |
735 |
int <b>check_module_symbol</b>(Module *<i>module</i>, |
736 |
const char *<i>symname</i>, |
737 |
void **<i>resultptr</i>, |
738 |
const char **<i>errorptr</i>)</div> |
739 |
|
740 |
<p>Both of these functions retrieve the value of the symbol |
741 |
<tt><i>symname</i></tt> in the module <tt><i>module</i></tt>; if |
742 |
<tt><i>module</i></tt> is <tt>NULL</tt>, the symbol is searched for in all |
743 |
loaded modules (if defined in more than one module, then an arbitrary |
744 |
module is used for the lookup). If the symbol is not defined in |
745 |
<tt><i>module</i></tt> but is defined in another module, then the result of |
746 |
the lookup is defined to be either <tt>NULL</tt> or the value of the symbol |
747 |
in the module in which it is defined. This undesirable behavior |
748 |
unfortunately cannot be avoided due to identical behavior by (at least) the |
749 |
glibc library used on Linux. When using static linking, the functions |
750 |
always return <tt>NULL</tt> for this case.</p> |
751 |
|
752 |
<p>The difference between their two functions is how they deal with the |
753 |
case of a nonexistent symbol. <tt>get_module_symbol()</tt> is intended for |
754 |
use when the symbol is assumed to exist; it returns the symbol's value |
755 |
directly if it exist, and logs a warning and returns <tt>NULL</tt> |
756 |
otherwise. The danger of using this for symbols that may legitimately not |
757 |
exist (other than generating spurious log messages) is that it is possible |
758 |
for a symbol to have the value zero (<tt>NULL</tt>), which would be |
759 |
indistinguishable from a symbol lookup failure. |
760 |
<tt>check_module_symbol()</tt>, on the other hands, takes two extra |
761 |
parameters, a pointer to a variable in which the result is to be stored |
762 |
on success and a pointer to a variable in which the relevant error message |
763 |
is to be stored on failure (either or both of which may be <tt>NULL</tt>), |
764 |
and returns nonzero on success, zero on failure. On success, the variable |
765 |
pointed to by <tt><i>resultptr</i></tt> is set to the value of the pointer, |
766 |
and the variable pointed to by <tt><i>errorptr</i></tt> is left unchanged; |
767 |
on failure, the variable pointed to by <tt><i>errorptr</i></tt> is set to a |
768 |
human-readable error string, and the variable pointed to by |
769 |
<tt><i>resultptr</i></tt> is left unchanged.</p> |
770 |
|
771 |
<p>Note that the "value of the symbol" here is the value in linker terms; |
772 |
in other words, when using these functions to access a variable, the value |
773 |
of the symbol is the <i>address</i> of the variable, not its value. To |
774 |
access the value of the <tt>s_NickServ</tt> string variable in an |
775 |
unspecified module, for example, one would write code like:</p> |
776 |
|
777 |
<div class="code">char **p_s_NickServ = get_module_symbol(NULL, "s_NickServ"); |
778 |
if (p_s_NickServ) { |
779 |
notice(*p_s_NickServ, user->nick, "message"); |
780 |
} else { |
781 |
/* Unable to resolve s_NickServ */ |
782 |
}</div> |
783 |
|
784 |
<p>It is also important to keep in mind that the value of such variables |
785 |
may change, or the module containing the variable may be unloaded, at any |
786 |
time. Accesses should therefore always be done by looking up the symbol, |
787 |
ensuring that the symbol exists, and referencing it through the returned |
788 |
pointer. Since this can incur significant overhead, however, another |
789 |
option (when the module name is known) is to use the "<tt>load module</tt>" |
790 |
and "<tt>unload module</tt>" callbacks to watch for the module to be loaded |
791 |
or unloaded; a single <tt>get_module_symbol()</tt> or |
792 |
<tt>check_module_symbol()</tt> will then suffice, and the returned variable |
793 |
pointer can be saved locally until the module is later unloaded. Many of |
794 |
the modules distributed with Services take this approach.</p> |
795 |
|
796 |
<p>The other method of accessing symbols in other modules is to simply |
797 |
reference the symbol as if it was an ordinary external variable or |
798 |
function. Doing this avoids the overhead of looking up the symbol every |
799 |
time it is to be used, or monitoring the relevant module for loads and |
800 |
unloads. However, it also requires the module containing the symbol to be |
801 |
loaded before the module that uses it; if the modules are not loaded in the |
802 |
correct order, <tt>load_module()</tt> will report an "unresolved symbol" |
803 |
error. For example, if module A exports a symbol <tt>symA</tt> which |
804 |
module B accesses directly, attempting to load module B before module A |
805 |
will cause an "unresolved symbol" error for <tt>symA</tt>, without giving |
806 |
module B a chance to manually resolve the symbol. As a general rule, |
807 |
therefore, it is recommended to avoid direct references to symbols from |
808 |
other modules, unless the other module can be reasonably expected to be |
809 |
loaded first (for example, many of the pseudoclients' sub-modules access |
810 |
symbols from their respective core modules in this fashion).</p> |
811 |
|
812 |
<p class="backlink"><a href="#top">Back to top</a></p> |
813 |
|
814 |
<!------------------------------------------------------------------------> |
815 |
<hr/> |
816 |
|
817 |
<h3 class="subsection-title" id="s5">4-5. Callbacks</h3> |
818 |
|
819 |
<p><i>Callbacks</i> are a method of allowing modules to signal other |
820 |
modules when certain events occur. A module first establishes a callback |
821 |
by registering it, giving it a name unique among all callbacks for that |
822 |
module (two callbacks in different modules can share the same name). Other |
823 |
modules can use that name to refer to the callback, and add functions to be |
824 |
called when the callback's event occurs (also referred to as <i>hooking |
825 |
into</i> the callback). The module which added the callback can then |
826 |
instruct the module subsystem to call each of those functions in turn when |
827 |
the requisite event occurs.</p> |
828 |
|
829 |
<p>The Services core also sets up a number of callbacks which can be hooked |
830 |
into by modules as necessary. A full list of callbacks available in the |
831 |
Services core and standard modules can be found in <a href="c.html">Appendix |
832 |
C</a>.</p> |
833 |
|
834 |
<p class="backlink"><a href="#top">Back to top</a></p> |
835 |
|
836 |
|
837 |
<h4 class="subsubsection-title" id="s5-1">4-5-1. Registering callbacks</h4> |
838 |
|
839 |
<p>A module that wishes to register a new callback can do so with the |
840 |
<tt>register_callback()</tt> routine (internally |
841 |
<tt>_register_callback()</tt>):</p> |
842 |
|
843 |
<div class="code">int <b>register_callback</b>([Module *<i>module</i>,] const char *<i>name</i>)</div> |
844 |
|
845 |
<p>This routine checks to ensure that the given module has not already |
846 |
registered a callback of the same name (by calling <tt>find_callback()</tt>, |
847 |
an internal helper function that looks for a callback by name in a given |
848 |
module), then adds the callback to the module's callback table with an |
849 |
empty callback function list. The return value is the ID value assigned to |
850 |
the callback (a value used when calling or removing the callback, both for |
851 |
efficiency and to eliminate the possibility of mistyping the callback name |
852 |
string when referring to it internally); a return value of -1 signals an |
853 |
error. Note that the module's <tt>THIS_MODULE</tt> macro (which evaluates |
854 |
to <tt>NULL</tt> when called by the core) is automatically passed to the |
855 |
function by the <tt>register_callback()</tt> macro in <tt>modules.h</tt>, |
856 |
like the <tt><i>caller</i></tt> parameter to <tt>use_module()</tt> and |
857 |
<tt>unuse_module()</tt>.</p> |
858 |
|
859 |
<p>When the callback is no longer needed, it can be unregistered by |
860 |
calling <tt>unregister_callback()</tt> (internally |
861 |
<tt>_unregister_callback()</tt>):</p> |
862 |
|
863 |
<div class="code">int <b>unregister_callback</b>([Module *<i>module</i>,] int <i>id</i>)</div> |
864 |
|
865 |
<p>The routine returns 1 if the callback was found and freed, 0 if the ID |
866 |
value given was invalid.</p> |
867 |
|
868 |
<p class="backlink"><a href="#top">Back to top</a></p> |
869 |
|
870 |
|
871 |
<h4 class="subsubsection-title" id="s5-2">4-5-2. Hooking into callbacks</h4> |
872 |
|
873 |
<p>Once a callback has been registered, other modules can add functions to |
874 |
or remove functions from the callback with the <tt>add_callback()</tt>, |
875 |
<tt>add_callback_pri()</tt>, and <tt>remove_callback()</tt> functions |
876 |
(internally <tt>_add_callback_pri()</tt> and |
877 |
<tt>_remove_callback</tt>—<tt>add_callback()</tt> is defined in terms |
878 |
of <tt>add_callback_pri()</tt>):</p> |
879 |
|
880 |
<div class="code">int <b>add_callback</b>(Module *<i>module</i>, |
881 |
const char *<i>name</i>, |
882 |
callback_t <i>callback</i>, |
883 |
[const Module *<i>caller</i>]) |
884 |
int <b>add_callback_pri</b>(Module *<i>module</i>, |
885 |
const char *<i>name</i>, |
886 |
callback_t <i>callback</i>, |
887 |
int <i>priority</i>, |
888 |
[const Module *<i>caller</i>]) |
889 |
int <b>remove_callback</b>(Module *<i>module</i>, |
890 |
const char *<i>name</i>, |
891 |
callback_t <i>callback</i>, |
892 |
[const Module *<i>caller</i>])</div> |
893 |
|
894 |
<p>The type of a callback function is defined as <tt>callback_t</tt>:</p> |
895 |
|
896 |
<div class="code">typedef int (*callback_t)()</div> |
897 |
|
898 |
<p>The number and type of parameters passed to the function depends on the |
899 |
particular callback, and thus the <tt>callback_t</tt> type is not a true |
900 |
prototype. The <tt>int</tt> return value is used both to return a result |
901 |
from the callback function itself and to control execution of the list of |
902 |
callback functions, with a nonzero value terminating execution, as |
903 |
described in <a href="#s5-3">section 4-5-3</a> below.</p> |
904 |
|
905 |
<p><tt>add_callback()</tt> and <tt>add_callback_pri()</tt> add the given |
906 |
function to the selected callback, returning nonzero on success, zero on |
907 |
error. In the case of <tt>add_callback_pri()</tt>, the callback function |
908 |
can be given a numeric priority; callback functions with higher priority |
909 |
values are called before those with lower values, and callback functions |
910 |
with the same priority value are called in the same order they were added. |
911 |
<tt>add_callback()</tt> is equivalent to <tt>add_callback_pri()</tt> with a |
912 |
priority of zero, and in fact is implemented as a macro that does exactly |
913 |
that. <i>Implementation note: Priorities were added to allow the |
914 |
<tt>operserv/sessions</tt> module to have its "<tt>user check</tt>" |
915 |
callback function, which increments the user count for a session if the |
916 |
user passes the session check, called last. This is arguably a bad design |
917 |
decision, as it would be better (if less efficient) to move the session |
918 |
count incrementing to the "<tt>user create</tt>" callback, and the current |
919 |
method cannot stop another module from adding a callback function at an |
920 |
even lower priority and causing the session count to "leak" if the |
921 |
lower-priority function rejects the user.</i></p> |
922 |
|
923 |
<p><tt>remove_callback()</tt> removes the given function from the selected |
924 |
callback, returning nonzero if the function was found and successfully |
925 |
removed, else zero. <tt>remove_callback()</tt> deliberately does not |
926 |
generate a log warning when used with a callback function that has not been |
927 |
added, in order to simplify modules' cleanup routines (so that they can |
928 |
call <tt>remove_callback()</tt> for all callbacks that may have potentially |
929 |
been added without having to keep track of which ones were in fact |
930 |
added).</p> |
931 |
|
932 |
<p class="backlink"><a href="#top">Back to top</a></p> |
933 |
|
934 |
|
935 |
<h4 class="subsubsection-title" id="s5-3">4-5-3. Calling callbacks</h4> |
936 |
|
937 |
<p>A module can instruct the module subsystem to call all callback |
938 |
functions for a particular callback with the <tt>call_callback()</tt> set |
939 |
of functions (actually macros, with the implementing function internally |
940 |
named <tt>_call_callback_5()</tt>):</p> |
941 |
|
942 |
<div class="code">int <b>call_callback</b>([Module *<i>module</i>,] int <i>id</i>) |
943 |
int <b>call_callback_1</b>([Module *<i>module</i>,] int <i>id</i>, |
944 |
void *<i>arg1</i>) |
945 |
int <b>call_callback_2</b>([Module *<i>module</i>,] int <i>id</i>, |
946 |
void *<i>arg1</i>, void *<i>arg2</i>) |
947 |
int <b>call_callback_3</b>([Module *<i>module</i>,] int <i>id</i>, |
948 |
void *<i>arg1</i>, void *<i>arg2</i>, void *<i>arg3</i>) |
949 |
int <b>call_callback_4</b>([Module *<i>module</i>,] int <i>id</i>, |
950 |
void *<i>arg1</i>, void *<i>arg2</i>, void *<i>arg3</i>, |
951 |
void *<i>arg4</i>) |
952 |
int <b>call_callback_5</b>([Module *<i>module</i>,] int <i>id</i>, |
953 |
void *<i>arg1</i>, void *<i>arg2</i>, void *<i>arg3</i>, |
954 |
void *<i>arg4</i>, void *<i>arg5</i>)</div> |
955 |
|
956 |
<p>As with <tt>register_module()</tt> and <tt>unregister_module()</tt>, |
957 |
the module handle of the calling module is automatically passed in the |
958 |
hidden <tt><i>module</i></tt> parameter.</p> |
959 |
|
960 |
<p>These functions all call the selected callback (specified by callback |
961 |
ID value, as returned from <tt>register_callback()</tt>), and differ only |
962 |
in the number of parameters passed to the callback. The parameters |
963 |
<tt><i>arg1</i></tt> through <tt><i>arg5</i></tt> are passed to the |
964 |
callback functions unchanged; the parameters are declared as the (more or |
965 |
less) generic type <tt>void *</tt>, but may be of any type, as the |
966 |
<tt>call_callback()</tt> macros take care of converting the parameters to |
967 |
<tt>void *</tt> to avoid type conversion warnings (but see |
968 |
<a href="11.html#s1">section 11-1</a> for problems with this method of |
969 |
passing parameters). It is the callback function's responsibility to |
970 |
ensure that it is declared with the correct parameter list.</p> |
971 |
|
972 |
<p>After checking the validity of the module and callback ID parameters, |
973 |
<tt>call_callback()</tt> calls each callback function that has been added |
974 |
to the callback, in priority and time order (see <a href="#s5-2">section |
975 |
4-5-2</a> about calling order). If any callback function returns a nonzero |
976 |
value, <tt>call_callback()</tt> stops immediately and returns that value, |
977 |
skipping the rest of the callback functions; if all callback functions |
978 |
return zero (or if there are no callback functions for the given callback), |
979 |
zero is returned. (-1 is returned if the callback ID is invalid.) Thus, |
980 |
callbacks should be designed so that a return value of zero from a callback |
981 |
function means "continue processing" and a nonzero value means "stop |
982 |
processing or take some other action".</p> |
983 |
|
984 |
<p class="backlink"><a href="#top">Back to top</a></p> |
985 |
|
986 |
<!------------------------------------------------------------------------> |
987 |
<hr/> |
988 |
|
989 |
<h3 class="subsection-title" id="s6">4-6. Adding a module to Services</h3> |
990 |
|
991 |
<p>Adding a new module to Services consists generally of the following |
992 |
steps:</p> |
993 |
|
994 |
<ul> |
995 |
<li>Create a subdirectory for the module under the <tt>modules</tt> |
996 |
directory.</li> |
997 |
<li>Write the module itself.</li> |
998 |
<li>Create a Makefile for the module (see <a href="10.html#s3-2">section |
999 |
10-3-2</a>).</li> |
1000 |
</ul> |
1001 |
|
1002 |
<p>For submodules of pre-existing modules, like new NickServ or ChanServ |
1003 |
features, the module can naturally go in the appropriate pre-existing |
1004 |
directory instead, with the corresponding Makefile modified to compile the |
1005 |
new module.</p> |
1006 |
|
1007 |
<p>For modules intended to be distributed separately from Services itself, |
1008 |
it is sufficient to distribute the subdirectory containing the module |
1009 |
source code and Makefile; by copying that directory into the <tt>modules</tt> |
1010 |
directory of a fresh Services distribution, the module Makefile will |
1011 |
automatically detect it and compile the module without any further |
1012 |
intervention on the part of the user. (See also |
1013 |
<a href="../3.html#10">section 3-10 of th user's manual</a>.)</p> |
1014 |
|
1015 |
<p>In addition to this section, sections <a href="2.html#s2">2-2</a> |
1016 |
(concerning utility functions) and <a href="2.html#s4">2-4</a> (concerning |
1017 |
logging), along with <a href="c.html">Appendix C</a> (containing a list of |
1018 |
core and standard module callbacks), provide useful information for module |
1019 |
development. Additionally, the following sections of this manual can be |
1020 |
helpful in writing different types of modules:</p> |
1021 |
|
1022 |
<ul> |
1023 |
<li><b>Protocol modules:</b> sections <a href="5.html">5</a> and |
1024 |
<a href="2.html#s5">2-5</a>, and particularly section |
1025 |
<a href="5.html#s6-14">5-6-14</a>, which discusses the Unreal |
1026 |
protocol module in detail.</li> |
1027 |
<li><b>Database modules:</b> sections <a href="6.html">6</a> and |
1028 |
<a href="2.html#s9-2">2-9-2</a>.</li> |
1029 |
<li><b>Pseudoclient modules:</b> sections <a href="7.html">7</a>, |
1030 |
<a href="2.html#s6">2-6</a>, <a href="2.html#s8">2-8</a>, |
1031 |
<a href="2.html#s10">2-10</a>, and <a href="6.html#s2">6-2</a>.</li> |
1032 |
</ul> |
1033 |
|
1034 |
<p class="backlink"><a href="#top">Back to top</a></p> |
1035 |
|
1036 |
<!------------------------------------------------------------------------> |
1037 |
<hr/> |
1038 |
|
1039 |
<p class="backlink"><a href="3.html">Previous section: Communication (socket) handling</a> | |
1040 |
<a href="index.html">Table of Contents</a> | |
1041 |
<a href="5.html">Next section: IRC server interface</a></p> |
1042 |
|
1043 |
</body> |
1044 |
</html> |