83
121
<link title="Nethtml" rel="Chapter" href="Nethtml.html">
84
122
<link title="Netstring_str" rel="Chapter" href="Netstring_str.html">
85
123
<link title="Netstring_pcre" rel="Chapter" href="Netstring_pcre.html">
86
<link title="Netstring_mt" rel="Chapter" href="Netstring_mt.html">
87
124
<link title="Netmappings" rel="Chapter" href="Netmappings.html">
88
125
<link title="Netaux" rel="Chapter" href="Netaux.html">
89
126
<link title="Nethttp" rel="Chapter" href="Nethttp.html">
127
<link title="Netpagebuffer" rel="Chapter" href="Netpagebuffer.html">
128
<link title="Netfs" rel="Chapter" href="Netfs.html">
129
<link title="Netglob" rel="Chapter" href="Netglob.html">
130
<link title="Netauth" rel="Chapter" href="Netauth.html">
131
<link title="Netsockaddr" rel="Chapter" href="Netsockaddr.html">
132
<link title="Netnumber" rel="Chapter" href="Netnumber.html">
133
<link title="Rtypes" rel="Chapter" href="Rtypes.html">
134
<link title="Xdr_mstring" rel="Chapter" href="Xdr_mstring.html">
135
<link title="Xdr" rel="Chapter" href="Xdr.html">
136
<link title="Netcompression" rel="Chapter" href="Netcompression.html">
90
137
<link title="Netchannels_tut" rel="Chapter" href="Netchannels_tut.html">
91
138
<link title="Netmime_tut" rel="Chapter" href="Netmime_tut.html">
92
139
<link title="Netsendmail_tut" rel="Chapter" href="Netsendmail_tut.html">
93
140
<link title="Netulex_tut" rel="Chapter" href="Netulex_tut.html">
94
141
<link title="Neturl_tut" rel="Chapter" href="Neturl_tut.html">
95
142
<link title="Netsys" rel="Chapter" href="Netsys.html">
143
<link title="Netsys_posix" rel="Chapter" href="Netsys_posix.html">
144
<link title="Netsys_pollset" rel="Chapter" href="Netsys_pollset.html">
145
<link title="Netlog" rel="Chapter" href="Netlog.html">
146
<link title="Netexn" rel="Chapter" href="Netexn.html">
147
<link title="Netsys_win32" rel="Chapter" href="Netsys_win32.html">
148
<link title="Netsys_pollset_posix" rel="Chapter" href="Netsys_pollset_posix.html">
149
<link title="Netsys_pollset_win32" rel="Chapter" href="Netsys_pollset_win32.html">
150
<link title="Netsys_pollset_generic" rel="Chapter" href="Netsys_pollset_generic.html">
151
<link title="Netsys_signal" rel="Chapter" href="Netsys_signal.html">
152
<link title="Netsys_oothr" rel="Chapter" href="Netsys_oothr.html">
153
<link title="Netsys_xdr" rel="Chapter" href="Netsys_xdr.html">
154
<link title="Netsys_rng" rel="Chapter" href="Netsys_rng.html">
155
<link title="Netsys_types" rel="Chapter" href="Netsys_types.html">
156
<link title="Netsys_mem" rel="Chapter" href="Netsys_mem.html">
157
<link title="Netsys_tmp" rel="Chapter" href="Netsys_tmp.html">
158
<link title="Netgzip" rel="Chapter" href="Netgzip.html">
96
159
<link title="Netpop" rel="Chapter" href="Netpop.html">
97
160
<link title="Rpc_auth_dh" rel="Chapter" href="Rpc_auth_dh.html">
98
161
<link title="Rpc_key_service" rel="Chapter" href="Rpc_key_service.html">
99
162
<link title="Rpc_time" rel="Chapter" href="Rpc_time.html">
100
163
<link title="Rpc_auth_local" rel="Chapter" href="Rpc_auth_local.html">
101
<link title="Rtypes" rel="Chapter" href="Rtypes.html">
102
<link title="Xdr" rel="Chapter" href="Xdr.html">
164
<link title="Rpc_ssl" rel="Chapter" href="Rpc_ssl.html">
165
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.html">
103
166
<link title="Rpc" rel="Chapter" href="Rpc.html">
104
167
<link title="Rpc_program" rel="Chapter" href="Rpc_program.html">
168
<link title="Rpc_util" rel="Chapter" href="Rpc_util.html">
105
169
<link title="Rpc_portmapper_aux" rel="Chapter" href="Rpc_portmapper_aux.html">
106
170
<link title="Rpc_packer" rel="Chapter" href="Rpc_packer.html">
107
171
<link title="Rpc_transport" rel="Chapter" href="Rpc_transport.html">
111
175
<link title="Rpc_portmapper" rel="Chapter" href="Rpc_portmapper.html">
112
176
<link title="Rpc_server" rel="Chapter" href="Rpc_server.html">
113
177
<link title="Rpc_auth_sys" rel="Chapter" href="Rpc_auth_sys.html">
178
<link title="Rpc_auth_gssapi" rel="Chapter" href="Rpc_auth_gssapi.html">
179
<link title="Rpc_proxy" rel="Chapter" href="Rpc_proxy.html">
114
180
<link title="Rpc_intro" rel="Chapter" href="Rpc_intro.html">
115
181
<link title="Rpc_mapping_ref" rel="Chapter" href="Rpc_mapping_ref.html">
116
<link title="Rpc_ssl" rel="Chapter" href="Rpc_ssl.html">
117
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.html">
182
<link title="Rpc_intro_gss" rel="Chapter" href="Rpc_intro_gss.html">
118
183
<link title="Shell_sys" rel="Chapter" href="Shell_sys.html">
119
184
<link title="Shell" rel="Chapter" href="Shell.html">
120
185
<link title="Shell_uq" rel="Chapter" href="Shell_uq.html">
121
<link title="Shell_mt" rel="Chapter" href="Shell_mt.html">
186
<link title="Shell_fs" rel="Chapter" href="Shell_fs.html">
122
187
<link title="Shell_intro" rel="Chapter" href="Shell_intro.html">
123
<link title="Netsmtp" rel="Chapter" href="Netsmtp.html"><title>Ocamlnet 2 Reference Manual : Netplex_cenv</title>
188
<link title="Netsmtp" rel="Chapter" href="Netsmtp.html">
189
<link title="Intro" rel="Chapter" href="Intro.html">
190
<link title="Platform" rel="Chapter" href="Platform.html">
191
<link title="Foreword" rel="Chapter" href="Foreword.html">
192
<link title="Ipv6" rel="Chapter" href="Ipv6.html"><link title="Debugging" rel="Section" href="#1_Debugging">
193
<link title="Logging" rel="Subsection" href="#2_Logging">
194
<link title="Timer" rel="Subsection" href="#2_Timer">
195
<link title="Container variables" rel="Subsection" href="#2_Containervariables">
196
<link title="System control" rel="Subsection" href="#2_Systemcontrol">
197
<link title="Inter-Container Communication" rel="Subsection" href="#2_InterContainerCommunication">
198
<link title="Direct container and admin interface access" rel="Subsection" href="#2_Directcontainerandadmininterfaceaccess">
199
<title>Ocamlnet 3 Reference Manual : Netplex_cenv</title>
126
202
<div class="navbar"><a href="Rpc_netplex.html">Previous</a>
127
203
<a href="index.html">Up</a>
128
<a href="Netplex_intro.html">Next</a>
204
<a href="Netplex_semaphore.html">Next</a>
130
206
<center><h1>Module <a href="type_Netplex_cenv.html">Netplex_cenv</a></h1></center>
132
208
<pre><span class="keyword">module</span> Netplex_cenv: <code class="code">sig</code> <a href="Netplex_cenv.html">..</a> <code class="code">end</code></pre>Container environment
135
Some helper functions to explore the environment from a container<br>
211
Some helper functions to explore the environment from a container.
212
Most of the following functions <b>must</b> be called from a container context,
213
i.e. from a process or thread that acts as container, otherwise
214
the exception <code class="code">Not_in_container_thread</code> is raised. There are also some
215
functions that can be called from controller context for convenience.<br>
136
216
<hr width="100%">
137
<pre><span class="keyword">exception</span> <a name="EXCEPTIONNot_in_container_thread"></a>Not_in_container_thread</pre>
217
<pre><span id="EXCEPTIONNot_in_container_thread"><span class="keyword">exception</span> Not_in_container_thread</span></pre>
138
218
<div class="info">
139
219
Raised when the caller's thread is not a container thread<br>
141
<pre><span class="keyword">val</span> <a name="VALself_cont"></a>self_cont : <code class="type">unit -> <a href="Netplex_types.container.html">Netplex_types.container</a></code></pre><div class="info">
142
Returns the container running the code of the caller<br>
144
<pre><span class="keyword">val</span> <a name="VALlog"></a>log : <code class="type"><a href="Netplex_types.html#TYPElevel">Netplex_types.level</a> -> string -> unit</code></pre><div class="info">
222
<span id="2_Logging"><h2>Logging</h2></span><br>
224
Logging functions can be invoked from both container and controller
226
<pre><span id="VALlog"><span class="keyword">val</span> log</span> : <code class="type"><a href="Netplex_types.html#TYPElevel">Netplex_types.level</a> -> string -> unit</code></pre><div class="info">
145
227
Writes a log message<br>
147
<pre><span class="keyword">val</span> <a name="VALlogf"></a>logf : <code class="type"><a href="Netplex_types.html#TYPElevel">Netplex_types.level</a> -> ('a, unit, string, unit) format4 -> 'a</code></pre><div class="info">
229
<pre><span id="VALlogf"><span class="keyword">val</span> logf</span> : <code class="type"><a href="Netplex_types.html#TYPElevel">Netplex_types.level</a> -> ('a, unit, string, unit) Pervasives.format4 -> 'a</code></pre><div class="info">
148
230
Writes a log message like <code class="code">printf</code><br>
b'\\ No newline at end of file'
232
<pre><span id="VALreport_connection_string"><span class="keyword">val</span> report_connection_string</span> : <code class="type">Unix.file_descr -> string -> string</code></pre><div class="info">
233
Output a log line for the <code class="code">netplex.connections</code> admin message.
234
The string is the detail to report.<br>
237
<span id="2_Timer"><h2>Timer</h2></span><br>
239
Timer functions can only be invoked from container contexts.
240
More documentation is available in <a href="Netplex_advanced.html#timers"><i>Running timers in containers</i></a>.<br>
241
<pre><span id="TYPEtimer"><span class="keyword">type</span> <code class="type"></code>timer</span> </pre>
246
<pre><span id="VALcreate_timer"><span class="keyword">val</span> create_timer</span> : <code class="type">(<a href="Netplex_cenv.html#TYPEtimer">timer</a> -> bool) -> float -> <a href="Netplex_cenv.html#TYPEtimer">timer</a></code></pre><div class="info">
247
<code class="code">create_timer f tmo</code>: Creates a timer with timeout value <code class="code">tmo</code>:
248
In <code class="code">tmo</code> seconds <code class="code">f</code> is called, and if this function returns <code class="code">true</code>,
249
the timer remains active, and another round of timing is arranged.
250
If the functions returns <code class="code">false</code> or raises an exception, the timer
254
Timers are also stopped on container shutdown.
257
Timers are attached to the container event system, and run only
258
if this event system runs.<br>
260
<pre><span id="VALcancel_timer"><span class="keyword">val</span> cancel_timer</span> : <code class="type"><a href="Netplex_cenv.html#TYPEtimer">timer</a> -> unit</code></pre><div class="info">
261
Cancels the timer: The callback function is not called any longer<br>
263
<pre><span id="VALcancel_all_timers"><span class="keyword">val</span> cancel_all_timers</span> : <code class="type">unit -> unit</code></pre><div class="info">
264
Cancels all active timers<br>
266
<pre><span id="VALtimer_id"><span class="keyword">val</span> timer_id</span> : <code class="type"><a href="Netplex_cenv.html#TYPEtimer">timer</a> -> int</code></pre><div class="info">
267
Returns an ID, e.g. useful for debugging<br>
270
<span id="2_Containervariables"><h2>Container variables</h2></span><br>
272
Container variables exist once per container. Primary access is
273
done via the <code class="code">var</code> and <code class="code">set_var</code> methods of the container class.
274
The following functions are often more convenient, however.
277
These functions can only be invoked from container contexts.
280
More documentation: <a href="Netplex_advanced.html#contvars"><i>Container variables</i></a><br>
281
<pre><span id="EXCEPTIONContainer_variable_not_found"><span class="keyword">exception</span> Container_variable_not_found</span> <span class="keyword">of</span> <code class="type">string</code></pre>
283
The variable does not exist<br>
285
<pre><span id="EXCEPTIONContainer_variable_type_mismatch"><span class="keyword">exception</span> Container_variable_type_mismatch</span> <span class="keyword">of</span> <code class="type">string</code></pre>
287
The (dynamically typed) variable has the wrong type<br>
289
<pre><span id="VALint_var"><span class="keyword">val</span> int_var</span> : <code class="type">string -> int</code></pre><pre><span id="VALstring_var"><span class="keyword">val</span> string_var</span> : <code class="type">string -> string</code></pre><pre><span id="VALfloat_var"><span class="keyword">val</span> float_var</span> : <code class="type">string -> float</code></pre><pre><span id="VALbool_var"><span class="keyword">val</span> bool_var</span> : <code class="type">string -> bool</code></pre><div class="info">
290
Access a variable with simple type. May raise
291
<code class="code">Container_variable_not_found</code> or <code class="code">Container_variable_type_mismatch</code><br>
293
<pre><span id="VALset_int_var"><span class="keyword">val</span> set_int_var</span> : <code class="type">string -> int -> unit</code></pre><pre><span id="VALset_string_var"><span class="keyword">val</span> set_string_var</span> : <code class="type">string -> string -> unit</code></pre><pre><span id="VALset_float_var"><span class="keyword">val</span> set_float_var</span> : <code class="type">string -> float -> unit</code></pre><pre><span id="VALset_bool_var"><span class="keyword">val</span> set_bool_var</span> : <code class="type">string -> bool -> unit</code></pre><div class="info">
294
Set a variable with simple type<br>
296
<pre><span id="VALmake_var_type"><span class="keyword">val</span> make_var_type</span> : <code class="type">('a -> <a href="Netplex_types.html#TYPEencap">Netplex_types.encap</a>) -><br> (<a href="Netplex_types.html#TYPEencap">Netplex_types.encap</a> -> 'a) -> (string -> 'a) * (string -> 'a -> unit)</code></pre><div class="info">
297
Create get and set functions for any (monomorphic) type. For example,
298
to create such function for a type <code class="code">foo</code>, do
301
<pre><code class="code">
302
module E = Netplex_encap.Make_encap(struct type t = foo end)
304
make_var_type E.wrap E.unwrap
308
Read on for using functors to create <code class="code">get</code> and <code class="code">set</code>.<br>
310
<pre><span class="keyword">module type</span> <a href="Netplex_cenv.TYPE.html">TYPE</a> = <code class="code">sig</code> <a href="Netplex_cenv.TYPE.html">..</a> <code class="code">end</code></pre><div class="info">
311
Just a (monomorphic) type <code class="code">t</code>
313
<pre><span class="keyword">module type</span> <a href="Netplex_cenv.VAR_TYPE.html">VAR_TYPE</a> = <code class="code">sig</code> <a href="Netplex_cenv.VAR_TYPE.html">..</a> <code class="code">end</code></pre><div class="info">
314
A (monomorphic) type <code class="code">t</code> with two functions <code class="code">get</code> and <code class="code">set</code>
315
accessing the container variables
317
<pre><span class="keyword">module</span> <a href="Netplex_cenv.Make_var_type.html">Make_var_type</a>: <div class="sig_block"><code class="code">functor (</code><code class="code">T</code><code class="code"> : </code><code class="type"><a href="Netplex_cenv.TYPE.html">TYPE</a></code><code class="code">) -> </code><code class="type"><a href="Netplex_cenv.VAR_TYPE.html">VAR_TYPE</a></code><code class="type"> with type t = T.t</code></div></pre><div class="info">
318
Creates <code class="code">get</code> and <code class="code">set</code> like <code class="code">make_var_type</code>.
321
<span id="2_Systemcontrol"><h2>System control</h2></span><br>
323
System control functions can be invoked from both container and controller
325
<pre><span id="VALsystem_shutdown"><span class="keyword">val</span> system_shutdown</span> : <code class="type">unit -> unit</code></pre><div class="info">
326
Initiates a system shutdown (like the <code class="code">shutdown</code> method of the
329
<pre><span id="VALsystem_restart"><span class="keyword">val</span> system_restart</span> : <code class="type">unit -> unit</code></pre><div class="info">
330
Initiates a system restart (like the <code class="code">restart</code> method of the
334
<span id="2_InterContainerCommunication"><h2>Inter-Container Communication</h2></span><br>
336
These functions can only be invoked from container contexts,
337
except <code class="code">send_message</code>.<br>
338
<pre><span id="VALsend_message"><span class="keyword">val</span> send_message</span> : <code class="type">string -> string -> string array -> unit</code></pre><div class="info">
339
<code class="code">send_message service_pattern msg_name msg_arguments</code>: Sends
340
a message to all services and message receivers matching
341
<code class="code">service_pattern</code>. The pattern may include the wildcard <code class="code">*</code>.
344
See the <a href="Netplex_types.controller-c.html#METHODsend_message"><code class="code">Netplex_types.controller.send_message</code></a> method for
345
the notification guarantees.
348
This function can be invoked from both container and controller
351
<pre><span id="VALlookup"><span class="keyword">val</span> lookup</span> : <code class="type">string -> string -> string option</code></pre><div class="info">
352
<code class="code">lookup service_name protocol_name</code> tries to find a Unix domain
353
socket for the service and returns it.
356
On Win32, the returned path refers to a file describing the
357
IPC mechanism. Use <a href="Netplex_sockserv.html#VALany_file_client_connector"><code class="code">Netplex_sockserv.any_file_client_connector</code></a>
358
to convert the path into an RPC connector.<br>
360
<pre><span id="VALlookup_container_sockets"><span class="keyword">val</span> lookup_container_sockets</span> : <code class="type">string -> string -> string array</code></pre><div class="info">
361
<code class="code">lookup_container_sockets service_name protocol_name</code>: returns
362
the Unix Domain paths of all container sockets for this service and
363
protocol. These are the sockets declared with address type
364
"container" in the config file.
367
On Win32, the returned paths refer to files describing the
368
IPC mechanism. Use <a href="Netplex_sockserv.html#VALany_file_client_connector"><code class="code">Netplex_sockserv.any_file_client_connector</code></a>
369
to convert the paths into RPC connectors.
372
Container sockets are explained here:
373
<a href="Netplex_advanced.html#contsocks"><i>Sending messages to individual containers</i></a><br>
376
<span id="2_Directcontainerandadmininterfaceaccess"><h2>Direct container and admin interface access</h2></span><br>
377
<pre><span id="VALself_cont"><span class="keyword">val</span> self_cont</span> : <code class="type">unit -> <a href="Netplex_types.container-c.html">Netplex_types.container</a></code></pre><div class="info">
378
Returns the container running the code of the caller,
379
or raise <code class="code">Not_in_container_thread</code> if called from outside a
380
container context.<br>
382
<pre><span id="VALself_obj"><span class="keyword">val</span> self_obj</span> : <code class="type">unit -><br> [ `Container of <a href="Netplex_types.container-c.html">Netplex_types.container</a><br> | `Controller of <a href="Netplex_types.controller-c.html">Netplex_types.controller</a> ]</code></pre><div class="info">
383
Returns the container or the controller running the code of the
384
caller, or raise <code class="code">Not_found</code> if called from
385
neither a container not a controller thread.<br>
387
<pre><span id="VALcurrent_sys_id"><span class="keyword">val</span> current_sys_id</span> : <code class="type">unit -> [ `Process of int | `Thread of int ]</code></pre><div class="info">
388
Returns the system-dependent thread identifier of the caller
389
(which must be in container or controller context)<br>
391
<pre><span id="VALadmin_connector"><span class="keyword">val</span> admin_connector</span> : <code class="type">unit -> <a href="Rpc_client.html#TYPEmode2">Rpc_client.mode2</a></code></pre><div class="info">
392
Determines the admin socket of the controller, and returns an RPC
393
client connector suitable for connecting with the admin interface
394
of the controller. For instance to initiate a system shutdown from
395
the context of a container:
398
<pre><code class="code"> let conn = Netplex_cenv.admin_connector() in
399
let client = Netplex_ctrl_clnt.Admin.V2.create_client2 conn in
400
Netplex_ctrl_clnt.Admin.V2.system_shutdown client ();
401
Rpc_client.shut_down client
405
Note that the admin interface is going to evolve, and it is advisable
406
to avoid admin calls whenever possible.
409
This function must be called from container context.<br>
411
<pre><span id="VALrun_in_controller_context"><span class="keyword">val</span> run_in_controller_context</span> : <code class="type"><a href="Netplex_types.controller-c.html">Netplex_types.controller</a> -> (unit -> unit) -> unit</code></pre><div class="info">
412
<code class="code">run_in_controller_context ctrl f</code>: Arranges that <code class="code">f()</code> is executed
413
in the context of the controller. <b>This is only possible for
414
multi-threading but not for multi-processing style!</b> For
415
programs using multi-processing, see <a href="Netplex_cenv.Make_lever.html"><code class="code">Netplex_cenv.Make_lever</code></a>
419
This function can be called from any thread. The function <code class="code">f</code> is
420
executed by pushing it onto the event queue, and calling it when
421
the pushed event is reached. This is usually a safe point for
422
many kinds of operations, but if controller methods are invoked
423
the details are left unspecified.
426
For example, this allows it to start helper threads via
427
<a href="Netplex_kit.html#VALadd_helper_service"><code class="code">Netplex_kit.add_helper_service</code></a> at any time.
430
An example can be found here: <a href="Netplex_advanced.html#levers"><i>Levers - calling controller functions from containers</i></a><br>
432
<pre><span id="VALrun_in_container_context"><span class="keyword">val</span> run_in_container_context</span> : <code class="type"><a href="Netplex_types.container-c.html">Netplex_types.container</a> -> (unit -> unit) -> unit</code></pre><div class="info">
433
<code class="code">run_in_container_context cont f</code>: Arranges that <code class="code">f()</code> is executed
434
in the context of the container <code class="code">cont</code>. <b>This is only possible for
435
multi-threading but not for multi-processing style!</b>
438
This function can be called from any thread. The function <code class="code">f</code> is
439
executed by pushing it onto the event queue, and calling it when
440
the pushed event is reached. This is usually a safe point for
441
many kinds of operations, but if container method are invoked
442
the details are left unspecified.
445
There is no guarantee that <code class="code">f</code> is called anytime soon - if the
446
container is busy with something else than with the event queue
447
the execution will be blocked until these other activities are
451
Levers are a way to send messages to the controller, and to effectively
452
run functions there that were previously registered.
455
More documentation: <a href="Netplex_advanced.html#levers"><i>Levers - calling controller functions from containers</i></a><br>
456
<pre><span class="keyword">module type</span> <a href="Netplex_cenv.FUN_TYPE.html">FUN_TYPE</a> = <code class="code">sig</code> <a href="Netplex_cenv.FUN_TYPE.html">..</a> <code class="code">end</code></pre><div class="info">
457
Abstraction for function types <code class="code">s->t</code>
459
<pre><span class="keyword">module type</span> <a href="Netplex_cenv.LEVER.html">LEVER</a> = <code class="code">sig</code> <a href="Netplex_cenv.LEVER.html">..</a> <code class="code">end</code></pre><pre><span class="keyword">module</span> <a href="Netplex_cenv.Make_lever.html">Make_lever</a>: <div class="sig_block"><code class="code">functor (</code><code class="code">T</code><code class="code"> : </code><code class="type"><a href="Netplex_cenv.FUN_TYPE.html">FUN_TYPE</a></code><code class="code">) -> </code><code class="type"><a href="Netplex_cenv.LEVER.html">LEVER</a></code><code class="type"> with type s=T.s and type r=T.r</code></div></pre><div class="info">
460
Creates a <code class="code">LEVER</code> module from a function type as specified in
461
<code class="code">FUN_TYPE</code>
464
<span id="1_Debugging"><h1>Debugging</h1></span><br>
465
<pre><span class="keyword">module</span> <a href="Netplex_cenv.Debug.html">Debug</a>: <code class="code">sig</code> <a href="Netplex_cenv.Debug.html">..</a> <code class="code">end</code></pre></body></html>
b'\\ No newline at end of file'