1LIBNODEUPDOWN(3) LIBNODEUPDOWN LIBNODEUPDOWN(3)
2
6 Introduction to writing nodeupdown modules or down
7
9 #include <nodeupdown.h>
10 #include <nodeupdown/nodeupdown_backend_module.h>
12 #include <nodeupdown/nodeupdown_clusterlist_module.h>
14 #include <nodeupdown/nodeupdown_config.h>
16 #include <nodeupdown/nodeupdown_config_module.h>
18 #include <nodeupdown/nodeupdown_constants.h>
20 #include <nodeupdown/nodeupdown_devel.h>
22 int nodeupdown_add_up_node(nodeupdown_t handle, const char *node);
24 int nodeupdown_add_down_node(nodeupdown_t handle, const char *node);
26 int nodeupdown_not_discovered_check(nodeupdown_t handle, const char
28 *node);
29 void nodeupdown_set_errnum(nodeupdown_t handle, int errnum);
31
34 Development of nodeupdown modules will rely on the nodeupdown develop‐
35 ment functions that give the module writer the ability to modify the
36 contents in the nodeupdown handle.
37 nodeupdown_add_up_node and nodeupdown_add_down_node add an up or down
39 node to the nodeupdown handle respectively.
40 nodeupdown_not_discovered_check will check if the specified node cur‐
42 rently exists in the handle. If it does not, the node will be added to
43 the internal list of down nodes.
44 nodeupdown_set_errnum will set the errnum inside the nodeupdown handle
46 to the specified errnum.
47 Additional information about the development of nodeupdown backend,
49 clusterlist, and config modules can be found below.
50
53 A nodeupdown backend module of the name 'foobar' can be written by com‐
54 piling a shared object library with the filename nodeupdown_back‐
55 end_foobar.so, and installing it in the nodeupdown package library
56 directory /usr/lib64/nodeupdown.
57 The backend module should define a structure of the following type:
59 struct nodeupdown_backend_module_info {
61 char *backend_module_name;
62 Nodeupdown_backend_default_hostname default_hostname;
63 Nodeupdown_backend_default_port default_port;
64 Nodeupdown_backend_default_timeout_len default_timeout_len;
65 Nodeupdown_backend_setup setup;
66 Nodeupdown_backend_cleanup cleanup;
67 Nodeupdown_backend_get_updown_data get_updown_data;
68 };
69 The structure should be named 'backend_module_info' and be populated
71 with the following information.
72 The field 'backend_module_name' should indicate the name of the backend
74 module.
75 The field 'default_hostname' should point to a function of the follow‐
77 ing type:
78 typedef char *(*Nodeupdown_backend_default_hostname)(nodeupdown_t);
80 The 'default_hostname' function returns a pointer to a string for the
82 default hostname for this backend module.
83 The field 'default_port' should point to a function of the following
85 type:
86 typedef int (*Nodeupdown_backend_default_port)(nodeupdown_t);
88 The 'default_port' function returns the default port for this backend
90 module.
91 The field 'default_timeout_len' should point to a function of the fol‐
93 lowing type:
94 typedef int (*Nodeupdown_backend_default_timeout_len)(nodeupdown_t);
96 The 'default_timeout_len' function returns the default timeout_len for
98 this backend module.
99 The field 'setup' should point to a function of the following type:
101 typedef int (*Nodeupdown_backend_setup)(nodeupdown_t);
103 The 'setup' function sets up the backend module with whatever initial‐
105 ization is necessary. It returns 0 on success, -1 on error.
106 The field 'cleanup' should point to a function of the following type:
108 typedef int (*Nodeupdown_backend_cleanup)(nodeupdown_t);
110 The 'cleanup' function cleans up the backend module from earlier ini‐
112 tializations. It returns 0 on success, -1 on error.
113 The field 'get_updown_data' should point to a function of the following
115 type:
116 typedef int (*Nodeupdown_backend_get_updown_data)(nodeupdown_t, const
118 char *, unsigned int, unsigned int, char *);
119 The 'get_updown_data' function retrieves all updown data from the back‐
121 end technology and stores it in the nodeupdown_t handle. The nodeup‐
122 down development functions nodeupdown_add_up_node and nodeup‐
123 down_add_down_node should be used to add the up or down nodes into the
124 handle. 'get_updown_data' is passed a hostname, port, timeout_len, and
125 reserved fields similar to nodeupdown_load_data(3). If values were
126 passed to nodeupdown_load_data(3), they are forwarded on to
127 'get_updown_data'. However, if defaults were passed to nodeup‐
128 down_load_data(3) the appropriate values have already been read and
129 compauted from configuration modules, configuration files, or the above
130 backend default functions.
131 All of the above functions must be defined in the module and listed in
133 the 'backend_module_info' structure.
134
137 A nodeupdown clusterlist module of the name 'foobar' can be written by
138 compiling a shared object library with the filename nodeupdown_clus‐
139 terlist_foobar.so, and installing it in the nodeupdown package library
140 directory /usr/lib64/nodeupdown.
141 The clusterlist module should define a structure of the following type:
143 struct nodeupdown_clusterlist_module_info {
145 char *clusterlist_module_name;
146 Nodeupdown_clusterlist_setup setup;
147 Nodeupdown_clusterlist_cleanup cleanup;
148 Nodeupdown_clusterlist_get_numnodes get_numnodes;
149 Nodeupdown_clusterlist_is_node_in_cluster is_node_in_cluster;
150 Nodeupdown_clusterlist_get_nodename get_nodename;
151 Nodeupdown_clusterlist_compare_to_clusterlist compare_to_clusterlist;
152 };
153 The structure should be named 'clusterlist_module_info' and be popu‐
155 lated with the following information.
156 The field 'clusterlist_module_name' should indicate the name of the
158 clusterlist module.
159 The field 'setup' should point to a function of the following type:
161 typedef int (*Nodeupdown_clusterlist_setup)(nodeupdown_t);
163 The 'setup' function sets up the clusterlist module with whatever ini‐
165 tialization is necessary. It returns 0 on success, -1 on error.
166 The field 'cleanup' should point to a function of the following type:
168 typedef int (*Nodeupdown_clusterlist_cleanup)(nodeupdown_t);
170 The 'cleanup' function cleans up the clusterlist module from earlier
172 initializations. It returns 0 on success, -1 on error.
173 The field 'get_numnodes' should point to a function of the following
175 type:
176 typedef int (*Nodeupdown_clusterlist_get_numnodes)(nodeupdown_t);
178 The 'get_numnodes' function returns the number of nodes in the cluster,
180 or -1 on error.
181 The field 'is_node_in_cluster' should point to a function of the fol‐
183 lowing type:
184 typedef int (*Nodeupdown_clusterlist_is_node_in_cluster)(nodeupdown_t,
186 const char *);
187 The 'is_node_in_cluster' function is passed a nodename. It returns 1
189 if the specified node is in the cluster, 0 if not, and -1 on error.
190 The field 'get_nodename' should point to a function of the following
192 type:
193 typedef int (*Nodeupdown_clusterlist_get_nodename)(nodeupdown_t, const
195 char *, char *, unsigned int);
196 The 'get_nodename' function is passed a nodename, a buffer, and a buf‐
198 fer length. It determines the appropriate nodename to use and copies
199 it into the buffer. This function is primarily used to convert aliased
200 nodenames into the appropriate nodename to use for calculations. The
201 majority of clusterlist module writers will probably copy the nodename
202 directly into the buffer and not do any calculations. 'get_nodename'
203 returns 0 on success, -1 on error.
204 The field 'compare_to_clusterlist' should point to a function of the
206 following type:
207 typedef int (*Nodeupdown_clusterlist_compare_to_clusterlist)(nodeup‐
209 down_t);
210 The 'compare_to_clusterlist' function is used to determine any addi‐
212 tional down nodes in the cluster. Clusterlist module writers will typ‐
213 ically iterate through the clusterlist module's list of nodes, and pass
214 each one to nodeupdown_not_discovered_check.
215 All of the above functions must be defined in the module and listed in
217 the 'clusterlist_module_info' structure.
218
221 A nodeupdown config module of the name 'foobar' can be written by com‐
222 piling a shared object library with the filename nodeupdown_config_foo‐
223 bar.so, and installing it in the nodeupdown package library directory
224 /usr/lib64/nodeupdown.
225 The config module should define a structure of the following type:
227 struct nodeupdown_config_module_info {
229 char *config_module_name;
230 Nodeupdown_config_setup setup;
231 Nodeupdown_config_cleanup cleanup;
232 Nodeupdown_config_load_default load_default;
233 };
234 The structure should be named 'config_module_info' and be populated
236 with the following information.
237 The field 'config_module_name' should indicate the name of the config
239 module.
240 The field 'setup' should point to a function of the following type:
242 typedef int (*Nodeupdown_config_setup)(nodeupdown_t);
244 The 'setup' function sets up the config module with whatever initial‐
246 ization is necessary. It returns 0 on success, -1 on error.
247 The field 'cleanup' should point to a function of the following type:
249 typedef int (*Nodeupdown_config_cleanup)(nodeupdown_t);
251 The 'cleanup' function cleans up the config module from earlier ini‐
253 tializations. It returns 0 on success, -1 on error.
254 The field 'load_default' should point to a function of the following
256 type:
257 typedef int (*Nodeupdown_config_load_default)(nodeupdown_t, struct
259 nodeupdown_config *);
260 The 'load_default' function loads an alternate set of configuration
262 values and stores them within the configuration structure passed in.
263 All of the above functions must be defined in the module and listed in
265 the 'config_module_info' structure.
266 The structure nodeupdown_config is defined as:
268 struct nodeupdown_config {
270 char hostnames[NODEUPDOWN_CONFIG_HOSTNAMES_MAX+1][NODEUPDOWN_MAXHOSTNAMELEN+1];
271 int hostnames_len;
272 int hostnames_flag;
273 int port;
274 int port_flag;
275 int timeout_len;
276 int timeout_len_flag;
277 };
278 The 'hostnames' field should store an array of default hostnames for
280 nodeupdown_load_data(3).
281 The 'port' field should store the default port for nodeup‐
283 down_load_data(3).
284 The 'timeout_len' field should store the default timeout length for
286 nodeupdown_load_data(3).
287 Any parameter that is set in the configuration structure must have its
289 respective flag set. The 'hostnames' field must also have the loaded.
290
293 libnodeupdown(3)
294LLNL May 2005 LIBNODEUPDOWN(3)