1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="Start" href="index.html">
<link rel="previous" href="Equeue_howto.html">
<link rel="next" href="Netcgi_apache.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of extensions" rel=Appendix href="index_extensions.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class attributes" rel=Appendix href="index_attributes.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Uq_gtk" rel="Chapter" href="Uq_gtk.html">
<link title="Uq_tcl" rel="Chapter" href="Uq_tcl.html">
<link title="Equeue" rel="Chapter" href="Equeue.html">
<link title="Unixqueue" rel="Chapter" href="Unixqueue.html">
<link title="Unixqueue_pollset" rel="Chapter" href="Unixqueue_pollset.html">
<link title="Unixqueue_select" rel="Chapter" href="Unixqueue_select.html">
<link title="Uq_resolver" rel="Chapter" href="Uq_resolver.html">
<link title="Uq_engines" rel="Chapter" href="Uq_engines.html">
<link title="Uq_multiplex" rel="Chapter" href="Uq_multiplex.html">
<link title="Uq_transfer" rel="Chapter" href="Uq_transfer.html">
<link title="Uq_socks5" rel="Chapter" href="Uq_socks5.html">
<link title="Uq_io" rel="Chapter" href="Uq_io.html">
<link title="Uq_lwt" rel="Chapter" href="Uq_lwt.html">
<link title="Uq_libevent" rel="Chapter" href="Uq_libevent.html">
<link title="Uq_mt" rel="Chapter" href="Uq_mt.html">
<link title="Uq_client" rel="Chapter" href="Uq_client.html">
<link title="Uq_server" rel="Chapter" href="Uq_server.html">
<link title="Uq_datagram" rel="Chapter" href="Uq_datagram.html">
<link title="Uq_engines_compat" rel="Chapter" href="Uq_engines_compat.html">
<link title="Equeue_intro" rel="Chapter" href="Equeue_intro.html">
<link title="Equeue_howto" rel="Chapter" href="Equeue_howto.html">
<link title="Netcamlbox" rel="Chapter" href="Netcamlbox.html">
<link title="Netcgi_apache" rel="Chapter" href="Netcgi_apache.html">
<link title="Netcgi_modtpl" rel="Chapter" href="Netcgi_modtpl.html">
<link title="Netcgi_plex" rel="Chapter" href="Netcgi_plex.html">
<link title="Netcgi_common" rel="Chapter" href="Netcgi_common.html">
<link title="Netcgi" rel="Chapter" href="Netcgi.html">
<link title="Netcgi_ajp" rel="Chapter" href="Netcgi_ajp.html">
<link title="Netcgi_scgi" rel="Chapter" href="Netcgi_scgi.html">
<link title="Netcgi_cgi" rel="Chapter" href="Netcgi_cgi.html">
<link title="Netcgi_fcgi" rel="Chapter" href="Netcgi_fcgi.html">
<link title="Netcgi_dbi" rel="Chapter" href="Netcgi_dbi.html">
<link title="Netcgi1_compat" rel="Chapter" href="Netcgi1_compat.html">
<link title="Netcgi_test" rel="Chapter" href="Netcgi_test.html">
<link title="Netcgi_porting" rel="Chapter" href="Netcgi_porting.html">
<link title="Nethttp_client_conncache" rel="Chapter" href="Nethttp_client_conncache.html">
<link title="Nethttp_client" rel="Chapter" href="Nethttp_client.html">
<link title="Nettelnet_client" rel="Chapter" href="Nettelnet_client.html">
<link title="Netftp_data_endpoint" rel="Chapter" href="Netftp_data_endpoint.html">
<link title="Netftp_client" rel="Chapter" href="Netftp_client.html">
<link title="Nethttp_fs" rel="Chapter" href="Nethttp_fs.html">
<link title="Netftp_fs" rel="Chapter" href="Netftp_fs.html">
<link title="Netsmtp" rel="Chapter" href="Netsmtp.html">
<link title="Netpop" rel="Chapter" href="Netpop.html">
<link title="Netldap" rel="Chapter" href="Netldap.html">
<link title="Netclient_tut" rel="Chapter" href="Netclient_tut.html">
<link title="Netgss_bindings" rel="Chapter" href="Netgss_bindings.html">
<link title="Netgss" rel="Chapter" href="Netgss.html">
<link title="Nethttpd_types" rel="Chapter" href="Nethttpd_types.html">
<link title="Nethttpd_kernel" rel="Chapter" href="Nethttpd_kernel.html">
<link title="Nethttpd_reactor" rel="Chapter" href="Nethttpd_reactor.html">
<link title="Nethttpd_engine" rel="Chapter" href="Nethttpd_engine.html">
<link title="Nethttpd_services" rel="Chapter" href="Nethttpd_services.html">
<link title="Nethttpd_plex" rel="Chapter" href="Nethttpd_plex.html">
<link title="Nethttpd_util" rel="Chapter" href="Nethttpd_util.html">
<link title="Nethttpd_intro" rel="Chapter" href="Nethttpd_intro.html">
<link title="Netmcore" rel="Chapter" href="Netmcore.html">
<link title="Netmcore_camlbox" rel="Chapter" href="Netmcore_camlbox.html">
<link title="Netmcore_mempool" rel="Chapter" href="Netmcore_mempool.html">
<link title="Netmcore_heap" rel="Chapter" href="Netmcore_heap.html">
<link title="Netmcore_ref" rel="Chapter" href="Netmcore_ref.html">
<link title="Netmcore_array" rel="Chapter" href="Netmcore_array.html">
<link title="Netmcore_sem" rel="Chapter" href="Netmcore_sem.html">
<link title="Netmcore_mutex" rel="Chapter" href="Netmcore_mutex.html">
<link title="Netmcore_condition" rel="Chapter" href="Netmcore_condition.html">
<link title="Netmcore_queue" rel="Chapter" href="Netmcore_queue.html">
<link title="Netmcore_buffer" rel="Chapter" href="Netmcore_buffer.html">
<link title="Netmcore_matrix" rel="Chapter" href="Netmcore_matrix.html">
<link title="Netmcore_hashtbl" rel="Chapter" href="Netmcore_hashtbl.html">
<link title="Netmcore_process" rel="Chapter" href="Netmcore_process.html">
<link title="Netmcore_tut" rel="Chapter" href="Netmcore_tut.html">
<link title="Netmcore_basics" rel="Chapter" href="Netmcore_basics.html">
<link title="Netplex_types" rel="Chapter" href="Netplex_types.html">
<link title="Netplex_mp" rel="Chapter" href="Netplex_mp.html">
<link title="Netplex_mt" rel="Chapter" href="Netplex_mt.html">
<link title="Netplex_log" rel="Chapter" href="Netplex_log.html">
<link title="Netplex_controller" rel="Chapter" href="Netplex_controller.html">
<link title="Netplex_container" rel="Chapter" href="Netplex_container.html">
<link title="Netplex_sockserv" rel="Chapter" href="Netplex_sockserv.html">
<link title="Netplex_workload" rel="Chapter" href="Netplex_workload.html">
<link title="Netplex_main" rel="Chapter" href="Netplex_main.html">
<link title="Netplex_config" rel="Chapter" href="Netplex_config.html">
<link title="Netplex_kit" rel="Chapter" href="Netplex_kit.html">
<link title="Rpc_netplex" rel="Chapter" href="Rpc_netplex.html">
<link title="Netplex_cenv" rel="Chapter" href="Netplex_cenv.html">
<link title="Netplex_semaphore" rel="Chapter" href="Netplex_semaphore.html">
<link title="Netplex_sharedvar" rel="Chapter" href="Netplex_sharedvar.html">
<link title="Netplex_mutex" rel="Chapter" href="Netplex_mutex.html">
<link title="Netplex_encap" rel="Chapter" href="Netplex_encap.html">
<link title="Netplex_mbox" rel="Chapter" href="Netplex_mbox.html">
<link title="Netplex_internal" rel="Chapter" href="Netplex_internal.html">
<link title="Netplex_intro" rel="Chapter" href="Netplex_intro.html">
<link title="Netplex_advanced" rel="Chapter" href="Netplex_advanced.html">
<link title="Netplex_admin" rel="Chapter" href="Netplex_admin.html">
<link title="Netshm" rel="Chapter" href="Netshm.html">
<link title="Netshm_data" rel="Chapter" href="Netshm_data.html">
<link title="Netshm_hashtbl" rel="Chapter" href="Netshm_hashtbl.html">
<link title="Netshm_array" rel="Chapter" href="Netshm_array.html">
<link title="Netshm_intro" rel="Chapter" href="Netshm_intro.html">
<link title="Netstring_pcre" rel="Chapter" href="Netstring_pcre.html">
<link title="Netconversion" rel="Chapter" href="Netconversion.html">
<link title="Netchannels" rel="Chapter" href="Netchannels.html">
<link title="Netstream" rel="Chapter" href="Netstream.html">
<link title="Netmime_string" rel="Chapter" href="Netmime_string.html">
<link title="Netmime" rel="Chapter" href="Netmime.html">
<link title="Netsendmail" rel="Chapter" href="Netsendmail.html">
<link title="Neturl" rel="Chapter" href="Neturl.html">
<link title="Netaddress" rel="Chapter" href="Netaddress.html">
<link title="Netbuffer" rel="Chapter" href="Netbuffer.html">
<link title="Netmime_header" rel="Chapter" href="Netmime_header.html">
<link title="Netmime_channels" rel="Chapter" href="Netmime_channels.html">
<link title="Neturl_ldap" rel="Chapter" href="Neturl_ldap.html">
<link title="Netdate" rel="Chapter" href="Netdate.html">
<link title="Netencoding" rel="Chapter" href="Netencoding.html">
<link title="Netulex" rel="Chapter" href="Netulex.html">
<link title="Netaccel" rel="Chapter" href="Netaccel.html">
<link title="Netaccel_link" rel="Chapter" href="Netaccel_link.html">
<link title="Nethtml" rel="Chapter" href="Nethtml.html">
<link title="Netstring_str" rel="Chapter" href="Netstring_str.html">
<link title="Netmappings" rel="Chapter" href="Netmappings.html">
<link title="Netaux" rel="Chapter" href="Netaux.html">
<link title="Nethttp" rel="Chapter" href="Nethttp.html">
<link title="Netpagebuffer" rel="Chapter" href="Netpagebuffer.html">
<link title="Netfs" rel="Chapter" href="Netfs.html">
<link title="Netglob" rel="Chapter" href="Netglob.html">
<link title="Netauth" rel="Chapter" href="Netauth.html">
<link title="Netsockaddr" rel="Chapter" href="Netsockaddr.html">
<link title="Netnumber" rel="Chapter" href="Netnumber.html">
<link title="Netxdr_mstring" rel="Chapter" href="Netxdr_mstring.html">
<link title="Netxdr" rel="Chapter" href="Netxdr.html">
<link title="Netcompression" rel="Chapter" href="Netcompression.html">
<link title="Netunichar" rel="Chapter" href="Netunichar.html">
<link title="Netasn1" rel="Chapter" href="Netasn1.html">
<link title="Netasn1_encode" rel="Chapter" href="Netasn1_encode.html">
<link title="Netoid" rel="Chapter" href="Netoid.html">
<link title="Netstring_tstring" rel="Chapter" href="Netstring_tstring.html">
<link title="Netdn" rel="Chapter" href="Netdn.html">
<link title="Netx509" rel="Chapter" href="Netx509.html">
<link title="Netascii_armor" rel="Chapter" href="Netascii_armor.html">
<link title="Nettls_support" rel="Chapter" href="Nettls_support.html">
<link title="Netmech_scram" rel="Chapter" href="Netmech_scram.html">
<link title="Netmech_scram_gssapi" rel="Chapter" href="Netmech_scram_gssapi.html">
<link title="Netmech_scram_sasl" rel="Chapter" href="Netmech_scram_sasl.html">
<link title="Netmech_scram_http" rel="Chapter" href="Netmech_scram_http.html">
<link title="Netgssapi_support" rel="Chapter" href="Netgssapi_support.html">
<link title="Netgssapi_auth" rel="Chapter" href="Netgssapi_auth.html">
<link title="Netchannels_crypto" rel="Chapter" href="Netchannels_crypto.html">
<link title="Netx509_pubkey" rel="Chapter" href="Netx509_pubkey.html">
<link title="Netx509_pubkey_crypto" rel="Chapter" href="Netx509_pubkey_crypto.html">
<link title="Netsaslprep" rel="Chapter" href="Netsaslprep.html">
<link title="Netmech_plain_sasl" rel="Chapter" href="Netmech_plain_sasl.html">
<link title="Netmech_crammd5_sasl" rel="Chapter" href="Netmech_crammd5_sasl.html">
<link title="Netmech_digest_sasl" rel="Chapter" href="Netmech_digest_sasl.html">
<link title="Netmech_digest_http" rel="Chapter" href="Netmech_digest_http.html">
<link title="Netmech_krb5_sasl" rel="Chapter" href="Netmech_krb5_sasl.html">
<link title="Netmech_gs2_sasl" rel="Chapter" href="Netmech_gs2_sasl.html">
<link title="Netmech_spnego_http" rel="Chapter" href="Netmech_spnego_http.html">
<link title="Netchannels_tut" rel="Chapter" href="Netchannels_tut.html">
<link title="Netmime_tut" rel="Chapter" href="Netmime_tut.html">
<link title="Netsendmail_tut" rel="Chapter" href="Netsendmail_tut.html">
<link title="Netulex_tut" rel="Chapter" href="Netulex_tut.html">
<link title="Neturl_tut" rel="Chapter" href="Neturl_tut.html">
<link title="Netsys" rel="Chapter" href="Netsys.html">
<link title="Netsys_posix" rel="Chapter" href="Netsys_posix.html">
<link title="Netsys_pollset" rel="Chapter" href="Netsys_pollset.html">
<link title="Netlog" rel="Chapter" href="Netlog.html">
<link title="Netexn" rel="Chapter" href="Netexn.html">
<link title="Netsys_win32" rel="Chapter" href="Netsys_win32.html">
<link title="Netsys_pollset_posix" rel="Chapter" href="Netsys_pollset_posix.html">
<link title="Netsys_pollset_win32" rel="Chapter" href="Netsys_pollset_win32.html">
<link title="Netsys_pollset_generic" rel="Chapter" href="Netsys_pollset_generic.html">
<link title="Netsys_signal" rel="Chapter" href="Netsys_signal.html">
<link title="Netsys_oothr" rel="Chapter" href="Netsys_oothr.html">
<link title="Netsys_xdr" rel="Chapter" href="Netsys_xdr.html">
<link title="Netsys_rng" rel="Chapter" href="Netsys_rng.html">
<link title="Netsys_crypto_types" rel="Chapter" href="Netsys_crypto_types.html">
<link title="Netsys_types" rel="Chapter" href="Netsys_types.html">
<link title="Netsys_mem" rel="Chapter" href="Netsys_mem.html">
<link title="Netsys_tmp" rel="Chapter" href="Netsys_tmp.html">
<link title="Netsys_sem" rel="Chapter" href="Netsys_sem.html">
<link title="Netsys_pmanage" rel="Chapter" href="Netsys_pmanage.html">
<link title="Netsys_crypto" rel="Chapter" href="Netsys_crypto.html">
<link title="Netsys_tls" rel="Chapter" href="Netsys_tls.html">
<link title="Netsys_ciphers" rel="Chapter" href="Netsys_ciphers.html">
<link title="Netsys_digests" rel="Chapter" href="Netsys_digests.html">
<link title="Netsys_crypto_modes" rel="Chapter" href="Netsys_crypto_modes.html">
<link title="Netsys_gssapi" rel="Chapter" href="Netsys_gssapi.html">
<link title="Netsys_sasl_types" rel="Chapter" href="Netsys_sasl_types.html">
<link title="Netsys_sasl" rel="Chapter" href="Netsys_sasl.html">
<link title="Netsys_polypipe" rel="Chapter" href="Netsys_polypipe.html">
<link title="Netsys_polysocket" rel="Chapter" href="Netsys_polysocket.html">
<link title="Netsys_global" rel="Chapter" href="Netsys_global.html">
<link title="Nettls_gnutls_bindings" rel="Chapter" href="Nettls_gnutls_bindings.html">
<link title="Nettls_nettle_bindings" rel="Chapter" href="Nettls_nettle_bindings.html">
<link title="Nettls_gnutls" rel="Chapter" href="Nettls_gnutls.html">
<link title="Netunidata" rel="Chapter" href="Netunidata.html">
<link title="Netgzip" rel="Chapter" href="Netgzip.html">
<link title="Rpc_auth_local" rel="Chapter" href="Rpc_auth_local.html">
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.html">
<link title="Rpc" rel="Chapter" href="Rpc.html">
<link title="Rpc_program" rel="Chapter" href="Rpc_program.html">
<link title="Rpc_util" rel="Chapter" href="Rpc_util.html">
<link title="Rpc_portmapper_aux" rel="Chapter" href="Rpc_portmapper_aux.html">
<link title="Rpc_packer" rel="Chapter" href="Rpc_packer.html">
<link title="Rpc_transport" rel="Chapter" href="Rpc_transport.html">
<link title="Rpc_client" rel="Chapter" href="Rpc_client.html">
<link title="Rpc_simple_client" rel="Chapter" href="Rpc_simple_client.html">
<link title="Rpc_portmapper_clnt" rel="Chapter" href="Rpc_portmapper_clnt.html">
<link title="Rpc_portmapper" rel="Chapter" href="Rpc_portmapper.html">
<link title="Rpc_server" rel="Chapter" href="Rpc_server.html">
<link title="Rpc_auth_sys" rel="Chapter" href="Rpc_auth_sys.html">
<link title="Rpc_auth_gssapi" rel="Chapter" href="Rpc_auth_gssapi.html">
<link title="Rpc_proxy" rel="Chapter" href="Rpc_proxy.html">
<link title="Rpc_intro" rel="Chapter" href="Rpc_intro.html">
<link title="Rpc_mapping_ref" rel="Chapter" href="Rpc_mapping_ref.html">
<link title="Rpc_intro_gss" rel="Chapter" href="Rpc_intro_gss.html">
<link title="Shell_sys" rel="Chapter" href="Shell_sys.html">
<link title="Shell" rel="Chapter" href="Shell.html">
<link title="Shell_uq" rel="Chapter" href="Shell_uq.html">
<link title="Shell_fs" rel="Chapter" href="Shell_fs.html">
<link title="Shell_intro" rel="Chapter" href="Shell_intro.html">
<link title="Intro" rel="Chapter" href="Intro.html">
<link title="Platform" rel="Chapter" href="Platform.html">
<link title="Foreword" rel="Chapter" href="Foreword.html">
<link title="Ipv6" rel="Chapter" href="Ipv6.html">
<link title="Regexp" rel="Chapter" href="Regexp.html">
<link title="Tls" rel="Chapter" href="Tls.html">
<link title="Crypto" rel="Chapter" href="Crypto.html">
<link title="Authentication" rel="Chapter" href="Authentication.html">
<link title="Credentials" rel="Chapter" href="Credentials.html">
<link title="Gssapi" rel="Chapter" href="Gssapi.html">
<link title="Ocamlnet4" rel="Chapter" href="Ocamlnet4.html">
<link title="Get" rel="Chapter" href="Get.html"><link title="Integration into event-based programs" rel="Section" href="#events">
<title>Ocamlnet 4 Reference Manual : Netcamlbox</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Equeue_howto.html" title="Equeue_howto">Previous</a>
<a class="up" href="index.html" title="Index">Up</a>
<a class="post" href="Netcgi_apache.html" title="Netcgi_apache">Next</a>
</div>
<h1>Module <a href="type_Netcamlbox.html">Netcamlbox</a></h1>
<pre><span id="MODULENetcamlbox"><span class="keyword">module</span> Netcamlbox</span>: <code class="code">sig</code> <a href="Netcamlbox.html">..</a> <code class="code">end</code></pre><div class="info module top">
<div class="info-desc">
<p>Camlboxes are a fast IPC mechanism to send Ocaml values from one
process to another. Source and destination processes must run on
the same machine (no network). The Ocaml value is copied to a
shared memory object where it can be directly accessed by the
receiver without unmarshalling step. This means the sender writes
the value into the shared memory in a format that can immediately
interpreted by the receiver.</p>
<p>A camlbox is owned by the single receiving process. Only this process
(or a fork) can look for new messages and can read them. There can be
any number of sending processes, i.e. we have a n:1 message passing
scenario.</p>
<p>The receiver process creates the camlbox, and is seen as the owner.
The receiver is accountible for deleting the camlbox when it is no
longer needed.</p>
<p>The sender(s) can send messages to any existing camlbox. There is
no notification whether the messages are actually read. The sender,
however, blocks when the destination camlbox is full, and will only
proceed when the receiver makes room for new messages. If there is
space in the camlbox the sender does not need to synchronize with the
receiver, i.e. it is possible to put a message into the box when
the receiver is busy with something else (asynchronous send operation).</p>
<p>Camlboxes have a fixed capacity of messages, and the message slots
have a fixed maximum length. The messages can have any type with only
a few restrictions (e.g. no functions and no custom blocks). There is
no check whether the sender and the receiver assume the same type
of the messages. This is left to the user. Breaking this assumption
will lead to unpredictable effects, including program crashes.
It is strongly advised to only communicate between processes that
run the same executable.</p>
<p>The user is also responsible for keeping only references to
existing messages. It is possible to get a value pointer
for a certain message via <code class="code">camlbox_get</code> and then to delete the message.
The user must no longer access the value - once the value is deleted
it may be overwritten, and the program may crash. Another danger
is that message values are modified so that pointers to heap
values are put into the message. This may lead to delayed crashes
when the heap value is moved to a different location or is even
deleted by the garbage collector. There is nothing the camlbox
implementation can do about that. If this is a problem, it is
advised to use <code class="code">camlbox_get_copy</code> instead which is not dangerous
in this respect.</p>
<p>On the system level, camlboxes are stored in POSIX shared memory
objects. These objects have kernel persistence and continue to
live after the process creating the camlbox has terminated without
unlinking the box.</p>
<p>This module requires Ocaml 3.11 or newer. The system must support
POSIX shared memory and POSIX semaphores. Camlboxes may be used
in multi-threaded programs as long as the values <code class="code">camlbox</code> and
<code class="code">camlbox_sender</code> are not used by several threads at the same time.</p>
<p><b>Examples.</b> There a few examples in the distribution tarball
(examples/camlbox).</p>
<p><b>Multi-core:</b>
Camlboxes can be used to gain speed-ups on multi-cores. See
examples/camlbox/README in the distribution tarball for an example
how to accomplish this.</p>
<p><b>Integration into event-based programs:</b> See the section
below, <a href="Netcamlbox.html#events"><i>Integration into event-based programs</i></a>.</p>
</div>
</div>
<hr width="100%">
<p><b>Since OCaml-4.01:</b> This OCaml version changed the semantics of the
built-in primitives <code class="code">caml_modify</code> and <code class="code">caml_initialize</code>. Essentially,
it is no longer possible to modify OCaml values residing outside the
regular OCaml heap. As we do this inside Netcamlbox, this change affects
this library. Fortunately, there is a workaround on systems supporting
weak symbols (all ELF systems and OS X): Here, <code class="code">caml_modify</code> and
<code class="code">caml_initialize</code> are overridden by Netcamlbox so that they are again
compatible. Note that this is a global modification of the runtime
system!</p>
<p>Future versions of Ocamlnet may solve this problem differently.</p>
<pre><span id="TYPEcamlbox_address"><span class="keyword">type</span> <code class="type"></code>camlbox_address</span> = <code class="type">string</code> </pre>
<div class="info ">
<div class="info-desc">
<p>The address of a camlbox is a string that does not contain
slashes. Addresses are system-global.</p>
</div>
</div>
<pre><span id="TYPEcamlbox"><span class="keyword">type</span> <code class="type">'a</code> camlbox</span> </pre>
<div class="info ">
<div class="info-desc">
<p>A <code class="code">camlbox</code> may receive messages of type <code class="code">'a</code></p>
</div>
</div>
<pre><span id="TYPEcamlbox_sender"><span class="keyword">type</span> <code class="type">'a</code> camlbox_sender</span> </pre>
<div class="info ">
<div class="info-desc">
<p>An endpoint that may send messages of type <code class="code">'a</code> to a camlbox</p>
</div>
</div>
<pre><span id="EXCEPTIONEmpty"><span class="keyword">exception</span> Empty</span></pre>
<pre><span id="EXCEPTIONMessage_too_big"><span class="keyword">exception</span> Message_too_big</span></pre>
<pre><span id="VALcreate_camlbox"><span class="keyword">val</span> create_camlbox</span> : <code class="type"><a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a> -> int -> int -> 'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a></code></pre><div class="info ">
<div class="info-desc">
<p><code class="code">create_camlbox addr n size</code>: Creates a new camlbox for up to
<code class="code">n</code> messages of <code class="code">size</code> bytes. The messages are numbered from
0 to <code class="code">n-1</code>. The camlbox is only meaningful for the creating
process, and must not be directly accessed by other processes.
Other processes can only send using a <code class="code">camlbox_sender</code>.</p>
<p>It is an error if the camlbox already exists.</p>
<p>It is suggested that the result of <code class="code">create_camlbox</code> is immediately
coerced to the right type <code class="code">t</code>, e.g.</p>
<pre class="codepre"><code class="code"> let box = (create_camlbox addr n size : t camlbox)
</code></pre><p>as this ensures type safety for all following operations.</p>
<p><b>Note that camlboxes have kernel persistence! They are not
automatically deleted when the process finishes. Call <code class="code">unlink_camlbox</code>
to delete camlboxes.</b></p>
</div>
</div>
<pre><span id="VALunlink_camlbox"><span class="keyword">val</span> unlink_camlbox</span> : <code class="type"><a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a> -> unit</code></pre><div class="info ">
<div class="info-desc">
<p>Removes the global name of the camlbox. All functions requiring
a <code class="code">camlbox_address</code> as input will not find the box anymore. The
box, however, continues to exist until the receiver and the senders
are done with it.</p>
</div>
</div>
<pre><span id="VALformat_camlbox"><span class="keyword">val</span> format_camlbox</span> : <code class="type"><a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a> -><br> Unix.file_descr -> int -> int -> 'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a></code></pre><div class="info ">
<div class="info-desc">
<p><code class="code">format_camlbox addr fd n size</code>: The file <code class="code">fd</code> is mapped into memory,
and formatted as camlbox.</p>
<p>In Ocamlnet-3.6, the function got the extra <code class="code">camlbox_address</code> argument.</p>
</div>
</div>
<pre><span id="VALcamlbox_addr"><span class="keyword">val</span> camlbox_addr</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a> -> <a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a></code></pre><div class="info ">
<div class="info-desc">
<p>returns the address</p>
</div>
</div>
<pre><span id="VALcamlbox_saddr"><span class="keyword">val</span> camlbox_saddr</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox_sender">camlbox_sender</a> -> <a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a></code></pre><div class="info ">
<div class="info-desc">
<p>returns the address</p>
</div>
</div>
<pre><span id="VALcamlbox_fd"><span class="keyword">val</span> camlbox_fd</span> : <code class="type"><a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a> -> Unix.file_descr</code></pre><div class="info ">
<div class="info-desc">
<p>Opens a new file descriptor to this address</p>
</div>
</div>
<pre><span id="VALcamlbox_capacity"><span class="keyword">val</span> camlbox_capacity</span> : <code class="type"><a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a> -> int</code></pre><div class="info ">
<div class="info-desc">
<p>Returns the maximum number of messages <code class="code">n</code></p>
</div>
</div>
<pre><span id="VALcamlbox_bcapacity"><span class="keyword">val</span> camlbox_bcapacity</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a> -> int</code></pre><div class="info ">
<div class="info-desc">
<p>same for an already opened box</p>
</div>
</div>
<pre><span id="VALcamlbox_scapacity"><span class="keyword">val</span> camlbox_scapacity</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox_sender">camlbox_sender</a> -> int</code></pre><div class="info ">
<div class="info-desc">
<p>same for a box already opened for sending</p>
</div>
</div>
<pre><span id="VALcamlbox_msg_size"><span class="keyword">val</span> camlbox_msg_size</span> : <code class="type"><a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a> -> int</code></pre><div class="info ">
<div class="info-desc">
<p>Returns the max size of a message in bytes</p>
</div>
</div>
<pre><span id="VALcamlbox_bmsg_size"><span class="keyword">val</span> camlbox_bmsg_size</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a> -> int</code></pre><div class="info ">
<div class="info-desc">
<p>same for an already opened box</p>
</div>
</div>
<pre><span id="VALcamlbox_smsg_size"><span class="keyword">val</span> camlbox_smsg_size</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox_sender">camlbox_sender</a> -> int</code></pre><div class="info ">
<div class="info-desc">
<p>same for a box already opened for sending</p>
</div>
</div>
<pre><span id="VALcamlbox_messages"><span class="keyword">val</span> camlbox_messages</span> : <code class="type"><a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a> -> int</code></pre><div class="info ">
<div class="info-desc">
<p>Returns the number of messages at the moment</p>
</div>
</div>
<pre><span id="VALcamlbox_bmessages"><span class="keyword">val</span> camlbox_bmessages</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a> -> int</code></pre><div class="info ">
<div class="info-desc">
<p>same for an already opened box</p>
</div>
</div>
<pre><span id="VALcamlbox_smessages"><span class="keyword">val</span> camlbox_smessages</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox_sender">camlbox_sender</a> -> int</code></pre><div class="info ">
<div class="info-desc">
<p>same for a box already opened for sending</p>
</div>
</div>
<pre><span id="VALcamlbox_get"><span class="keyword">val</span> camlbox_get</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a> -> int -> 'a</code></pre><div class="info ">
<div class="info-desc">
<p><code class="code">camlbox_get box k</code>: Returns message number <code class="code">k</code> from <code class="code">box</code>.
The returned value lives in the camlbox, and using it is only
safe as long as the camlbox exists and the message is not
deleted.</p>
<p>If there is no message at <code class="code">k</code> the exception <code class="code">Empty</code> will be
raised.</p>
<p>The result value must have the same type as the sent value.
This is not checked, however. Violating this rule is likely
to crash the program.</p>
</div>
</div>
<pre><span id="VALcamlbox_get_copy"><span class="keyword">val</span> camlbox_get_copy</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a> -> int -> 'a</code></pre><div class="info ">
<div class="info-desc">
<p><code class="code">camlbox_get box k</code>: Returns a deep copy of message number <code class="code">k</code> from <code class="code">box</code>.
This is safer than <code class="code">camlbox_get</code>, because the returned value remains
valid when the message is deleted from the box.</p>
<p>If there is no message at <code class="code">k</code> the exception <code class="code">Empty</code> will be
raised.</p>
<p>The result value must have the same type as the sent value.
This is not checked, however. Violating this rule is likely
to crash the program.</p>
</div>
</div>
<pre><span id="VALcamlbox_delete"><span class="keyword">val</span> camlbox_delete</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a> -> int -> unit</code></pre><div class="info ">
<div class="info-desc">
<p><code class="code">camlbox_delete box k</code>: Deletes the message number <code class="code">k</code> from <code class="code">box</code>.
Any value obtained via <code class="code">camlbox_get</code> for a message or a part
of a message becomes invalid and must not be used anymore.
There is no way to check this - violating this rule is likely
to crash the program. (In doubt use <code class="code">camlbox_get_copy</code> instead
which cannot interfer with <code class="code">camlbox_delete</code>.)</p>
<p>If there is no message at <code class="code">k</code> the exception <code class="code">Empty</code> will be
raised.</p>
</div>
</div>
<pre><span id="VALcamlbox_wait"><span class="keyword">val</span> camlbox_wait</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a> -> int list</code></pre><div class="info ">
<div class="info-desc">
<p>Waits until new messages arrive, and return the message numbers.
A new message is only reported once by <code class="code">camlbox_wait</code>. The
order of the messages is not specified.</p>
<p>Only one thread at a time must wait for new messages.</p>
<p>It is allowed that this function returns the empty list.</p>
</div>
</div>
<pre><span id="VALcamlbox_cancel_wait"><span class="keyword">val</span> camlbox_cancel_wait</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox">camlbox</a> -> unit</code></pre><div class="info ">
<div class="info-desc">
<p>Cancels a <code class="code">camlbox_wait</code> operation called by a different thread</p>
</div>
</div>
<pre><span id="VALcamlbox_sender"><span class="keyword">val</span> camlbox_sender</span> : <code class="type"><a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a> -> 'a <a href="Netcamlbox.html#TYPEcamlbox_sender">camlbox_sender</a></code></pre><div class="info ">
<div class="info-desc">
<p>Prepares for sending.</p>
<p>It is suggested that the result of <code class="code">camlbox_sender</code> is immediately
coerced to the right type <code class="code">t</code>, e.g.</p>
<pre class="codepre"><code class="code"> let box = (camlbox_sender addr : t camlbox_sender)
</code></pre><p>as this ensures type safety for all following operations.</p>
</div>
</div>
<pre><span id="VALcamlbox_sender_of_fd"><span class="keyword">val</span> camlbox_sender_of_fd</span> : <code class="type"><a href="Netcamlbox.html#TYPEcamlbox_address">camlbox_address</a> -> Unix.file_descr -> 'a <a href="Netcamlbox.html#TYPEcamlbox_sender">camlbox_sender</a></code></pre><div class="info ">
<div class="info-desc">
<p>Gets a sender for a file descriptor from <code class="code">camlbox_fd</code>.</p>
<p>Ocamlnet-3.6: new arg <code class="code">camlbox_address</code></p>
</div>
</div>
<pre><span id="VALcamlbox_send"><span class="keyword">val</span> camlbox_send</span> : <code class="type">?prefer:int -><br> ?slot:int Stdlib.ref -> 'a <a href="Netcamlbox.html#TYPEcamlbox_sender">camlbox_sender</a> -> 'a -> unit</code></pre><div class="info ">
<div class="info-desc">
<p>Sends a message to a camlbox. The value must be boxed (neither <code class="code">char</code>,
<code class="code">bool</code>, <code class="code">int</code>, nor a variant type), and a number of restrictions apply:</p>
<ul>
<li>The size of the representation must not exceed the maximum
message size of the camlbox, or the exception <code class="code">Message_too_big</code>
is raised.</li>
<li>Objects, closures, and lazy values are not supported</li>
<li>Abstract and custom block values are not supported except
bigarrays, <code class="code">int32</code>, <code class="code">int64</code>, and <code class="code">nativeint</code>.</li>
<li>Atoms (like empty arrays) may cause problems when the message
is extracted by <code class="code">camlbox_get</code> because atoms are duplicated,
and no longer unique. For example, a test <code class="code">if array=[||] then...</code>
is likely not to work. Use <code class="code">if Array.length array = 0 then...</code>,
or use <code class="code">camlbox_get_copy</code> for extraction.</li>
</ul>
<p>The value is copied to the receiving camlbox.</p>
<p>This function blocks until the receiving camlbox has free space.</p>
<p>Several threads may try to send messages at the same time.</p>
<p><code class="code">prefer</code>: suggests a slot for sending
<code class="code">slot</code>: the actual slot number is stored here</p>
</div>
</div>
<pre><span id="VALcamlbox_wake"><span class="keyword">val</span> camlbox_wake</span> : <code class="type">'a <a href="Netcamlbox.html#TYPEcamlbox_sender">camlbox_sender</a> -> unit</code></pre><div class="info ">
<div class="info-desc">
<p>Sends an "empty message" - this only means that if the receiving
thread is waiting for new messages it is interrupted and
<code class="code">camlbox_wait</code> will return the empty list.</p>
<p>This function is non-blocking.</p>
</div>
</div>
<h3 id="events">Integration into event-based programs</h3>
<p>The functions <code class="code">camlbox_wait</code> and <code class="code">camlbox_send</code> may both block the
execution of the program when no message has arrived, and no space
is available, respectively. This is a challenge for event-based
programs where all waiting is bound to events on file descriptors.</p>
<p>Generally, Camlboxes use semaphores for speed. The results are good,
often only 4 microseconds for sending and receiving a short
message. This is only possible because semaphores implement a fast
path where the help of the kernel is not needed, i.e. no context
switch happens. This is basically incompatible with the style of
waiting implemented for file descriptors, because this kind of
waiting for an event must always go through the kernel, and is
thus slower by design.</p>
<p>But anyway, what to do if Camlboxes need to be integrated into
a program that bases already on file descriptor polling? Of course,
speed will decrease, but maybe not dramatically. We assume here
that the program uses <a href="Unixqueue.html"><code class="code">Unixqueue</code></a>s as the basic data structure
for organizing polling.</p>
<p>If the program can use the Netmulticore library, there is a very
simple solution. The condition variables provided by this library
allow the integration into Unixqueues, see <a href="Netmcore_condition.html"><code class="code">Netmcore_condition</code></a>.
The condition variable is signalled whenever a new message is put
into the Camlbox, and the receiver waits until this signal arrives.
The function <a href="Netmcore_condition.html#VALwait_e"><code class="code">Netmcore_condition.wait_e</code></a> permits it to integrate
waiting into a Unixqueue.</p>
<p>Otherwise, if Netmulticore is no option (e.g. because the processes
are unrelated that communicate via Camlboxes), the other workaround
is to use threads. A special thread is set up which waits for new
Camlbox messages. Whenever a message arrives, an engine is notified
via a <a href="Uq_engines.html#VALsignal_engine"><code class="code">Uq_engines.signal_engine</code></a> (which is thread-safe). This engine
can run in a different thread.</p>
<pre><span id="MODULEDebug"><span class="keyword">module</span> <a href="Netcamlbox.Debug.html">Debug</a></span>: <code class="code">sig</code> <a href="Netcamlbox.Debug.html">..</a> <code class="code">end</code></pre></body></html>
|
