<!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">
<link rel="Start" href="index.html">
<link rel="previous" href="Netsys_types.html">
<link rel="next" href="Netsys_tmp.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.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="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_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="Equeue_intro" rel="Chapter" href="Equeue_intro.html">
<link title="Equeue_howto" rel="Chapter" href="Equeue_howto.html">
<link title="Uq_ssl" rel="Chapter" href="Uq_ssl.html">
<link title="Https_client" rel="Chapter" href="Https_client.html">
<link title="Uq_tcl" rel="Chapter" href="Uq_tcl.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_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="Netcgi_plex" rel="Chapter" href="Netcgi_plex.html">
<link title="Http_client_conncache" rel="Chapter" href="Http_client_conncache.html">
<link title="Http_client" rel="Chapter" href="Http_client.html">
<link title="Telnet_client" rel="Chapter" href="Telnet_client.html">
<link title="Ftp_data_endpoint" rel="Chapter" href="Ftp_data_endpoint.html">
<link title="Ftp_client" rel="Chapter" href="Ftp_client.html">
<link title="Http_fs" rel="Chapter" href="Http_fs.html">
<link title="Ftp_fs" rel="Chapter" href="Ftp_fs.html">
<link title="Netclient_tut" rel="Chapter" href="Netclient_tut.html">
<link title="Netgssapi" rel="Chapter" href="Netgssapi.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="Netmech_scram" rel="Chapter" href="Netmech_scram.html">
<link title="Netmech_scram_gssapi" rel="Chapter" href="Netmech_scram_gssapi.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_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="Netconversion" rel="Chapter" href="Netconversion.html">
<link title="Netchannels" rel="Chapter" href="Netchannels.html">
<link title="Netstream" rel="Chapter" href="Netstream.html">
<link title="Mimestring" rel="Chapter" href="Mimestring.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="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="Rtypes" rel="Chapter" href="Rtypes.html">
<link title="Xdr_mstring" rel="Chapter" href="Xdr_mstring.html">
<link title="Xdr" rel="Chapter" href="Xdr.html">
<link title="Netcompression" rel="Chapter" href="Netcompression.html">
<link title="Netunichar" rel="Chapter" href="Netunichar.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="Netstring_pcre" rel="Chapter" href="Netstring_pcre.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_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="Netgzip" rel="Chapter" href="Netgzip.html">
<link title="Netpop" rel="Chapter" href="Netpop.html">
<link title="Rpc_auth_dh" rel="Chapter" href="Rpc_auth_dh.html">
<link title="Rpc_key_service" rel="Chapter" href="Rpc_key_service.html">
<link title="Rpc_time" rel="Chapter" href="Rpc_time.html">
<link title="Rpc_auth_local" rel="Chapter" href="Rpc_auth_local.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="Rpc_ssl" rel="Chapter" href="Rpc_ssl.html">
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.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="Netsmtp" rel="Chapter" href="Netsmtp.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="General" rel="Section" href="#2_General">
<link title="Allocation and memory-mapping" rel="Section" href="#2_Allocationandmemorymapping">
<link title="Interpreting memory as values" rel="Section" href="#2_Interpretingmemoryasvalues">
<link title="I/O using memory as buffers" rel="Section" href="#2_IOusingmemoryasbuffers">
<link title="Buffer pools" rel="Section" href="#2_Bufferpools">
<title>Ocamlnet 3 Reference Manual : Netsys_mem</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Netsys_types.html" title="Netsys_types">Previous</a>
<a class="up" href="index.html" title="Index">Up</a>
<a class="post" href="Netsys_tmp.html" title="Netsys_tmp">Next</a>
</div>
<h1>Module <a href="type_Netsys_mem.html">Netsys_mem</a></h1>
<pre><span class="keyword">module</span> Netsys_mem: <code class="code">sig</code> <a href="Netsys_mem.html">..</a> <code class="code">end</code></pre><div class="info">
Bigarrays as memory buffers<br>
</div>
<hr width="100%">
<pre><span id="TYPEmemory"><span class="keyword">type</span> <code class="type"></code>memory</span> = <code class="type"><a href="Netsys_types.html#TYPEmemory">Netsys_types.memory</a></code> </pre>
<div class="info">
We consider 1-dimensional bigarrays of chars as memory buffers.
They have the useful property that the garbage collector cannot
relocate them, i.e. the address is fixed. Also, one can mmap
a file, and connect the bigarray with shared memory.<br>
</div>
<br>
<h2 id="2_General">General</h2><br>
<pre><span id="VALblit_memory_to_string"><span class="keyword">val</span> blit_memory_to_string</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> string -> int -> int -> unit</code></pre><div class="info">
<code class="code">blit_memory_to_string src srcoff dst dstoff len</code> copies <code class="code">len</code> characters
from buffer <code class="code">src</code>, starting at character number <code class="code">srcoff</code>, to
string <code class="code">dst</code>, starting at character number <code class="code">dstoff</code>
<p>
Raise <code class="code">Invalid_argument</code> if <code class="code">srcoff</code> and <code class="code">len</code> do not
designate a valid subbuffer of <code class="code">src</code>, or if <code class="code">dstoff</code> and <code class="code">len</code>
do not designate a valid substring of <code class="code">dst</code>.<br>
</div>
<pre><span id="VALblit_memory_to_string_unsafe"><span class="keyword">val</span> blit_memory_to_string_unsafe</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> string -> int -> int -> unit</code></pre><div class="info">
Unsafe version<br>
</div>
<pre><span id="VALblit_string_to_memory"><span class="keyword">val</span> blit_string_to_memory</span> : <code class="type">string -> int -> <a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> unit</code></pre><div class="info">
<code class="code">blit_string_to_memory src srcoff dst dstoff len</code> copies <code class="code">len</code> characters
from string <code class="code">src</code>, starting at character number <code class="code">srcoff</code>, to
buffer <code class="code">dst</code>, starting at character number <code class="code">dstoff</code>
<p>
Raise <code class="code">Invalid_argument</code> if <code class="code">srcoff</code> and <code class="code">len</code> do not
designate a valid substring of <code class="code">src</code>, or if <code class="code">dstoff</code> and <code class="code">len</code>
do not designate a valid subbuffer of <code class="code">dst</code>.<br>
</div>
<pre><span id="VALblit_string_to_memory_unsafe"><span class="keyword">val</span> blit_string_to_memory_unsafe</span> : <code class="type">string -> int -> <a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> unit</code></pre><div class="info">
Unsafe version<br>
</div>
<pre><span id="VALmemory_address"><span class="keyword">val</span> memory_address</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> nativeint</code></pre><div class="info">
Returns the start address of the buffer<br>
</div>
<pre><span id="VALmemory_of_bigarray"><span class="keyword">val</span> memory_of_bigarray</span> : <code class="type">('a, 'b, 'c) Bigarray.Genarray.t -> <a href="Netsys_mem.html#TYPEmemory">memory</a></code></pre><pre><span id="VALmemory_of_bigarray_1"><span class="keyword">val</span> memory_of_bigarray_1</span> : <code class="type">('a, 'b, 'c) Bigarray.Array1.t -> <a href="Netsys_mem.html#TYPEmemory">memory</a></code></pre><pre><span id="VALmemory_of_bigarray_2"><span class="keyword">val</span> memory_of_bigarray_2</span> : <code class="type">('a, 'b, 'c) Bigarray.Array2.t -> <a href="Netsys_mem.html#TYPEmemory">memory</a></code></pre><pre><span id="VALmemory_of_bigarray_3"><span class="keyword">val</span> memory_of_bigarray_3</span> : <code class="type">('a, 'b, 'c) Bigarray.Array3.t -> <a href="Netsys_mem.html#TYPEmemory">memory</a></code></pre><div class="info">
These functions return an arbitrary bigarray as <code class="code">memory</code>.
<p>
Due to a bug in the OCaml runtime, this is for now limited to
arrays of up to 2G size (in bytes). (The bug exists at least
up to OCaml-3.12.1.)<br>
</div>
<br>
<h2 id="2_Allocationandmemorymapping">Allocation and memory-mapping</h2><br>
<pre><span id="VALgetpagesize"><span class="keyword">val</span> getpagesize</span> : <code class="type">unit -> int</code></pre><div class="info">
Returns the size of a page as reported by <code class="code">sysconf</code>.
<p>
On many systems, a page has 4096 bytes, but this cannot be relied
upon.
<p>
This function is only available if the system has <code class="code">sysconf</code>.<br>
</div>
<pre><span id="VALpagesize"><span class="keyword">val</span> pagesize</span> : <code class="type">int</code></pre><div class="info">
The best guess at the page size<br>
</div>
<pre><span id="VALalloc_memory_pages"><span class="keyword">val</span> alloc_memory_pages</span> : <code class="type">?addr:nativeint -> ?exec:bool -> int -> <a href="Netsys_mem.html#TYPEmemory">memory</a></code></pre><div class="info">
Allocates memory in units of pages. The memory buffer will start
on a page boundary.
<p>
The passed int is the requested number of <b>bytes</b>. The size of
the buffer is rounded up so a whole number of pages is allocated.
<p>
Optionally, one can request a certain address <code class="code">addr</code> (which must
be a multiple of the page size). There is, however, no guarantee
that this wish can be fulfilled. In any way, one should check with
<code class="code">memory_address</code> what the start address really is.
<p>
If <code class="code">exec</code>, the memory region is marked as executable.
<p>
This function is only available if the system has <code class="code">sysconf</code>, <code class="code">mmap</code>,
and allows to allocate anonymous memory with <code class="code">mmap</code> (outside POSIX
but common).<br>
</div>
<pre><span id="VALalloc_aligned_memory"><span class="keyword">val</span> alloc_aligned_memory</span> : <code class="type">int -> int -> <a href="Netsys_mem.html#TYPEmemory">memory</a></code></pre><div class="info">
<code class="code">alloc_aligned_memory alignment size</code>: Allocates a buffer of <code class="code">size</code>
whose start address is a multiple of <code class="code">alignment</code>. The <code class="code">alignment</code>
must be a power of two, and at least <code class="code">Sys.word_size/8</code>.
<p>
Aligned memory can be useful for ensuring that the whole memory
block is in the same cache line. A cache line typically has
64 or 128 bytes - but this is very platform-specific. (Linux:
look at <code class="code">/proc/cpuinfo</code>.)
<p>
This function is only available if the system has <code class="code">posix_memalign</code>.<br>
</div>
<pre><span id="VALmemory_map_file"><span class="keyword">val</span> memory_map_file</span> : <code class="type">Unix.file_descr -><br> ?pos:int64 -> ?addr:nativeint -> bool -> int -> <a href="Netsys_mem.html#TYPEmemory">memory</a></code></pre><div class="info">
<code class="code">memory_map_file fd shared size</code>: Maps <code class="code">size</code> bytes of the file
<code class="code">fd</code> into memory, and returns the memory buffer like
<code class="code">Bigarray.Array1.map_file</code>. <code class="code">pos</code> and <code class="code">shared</code> have the same
meaning as there. In <code class="code">addr</code> one can suggest a start address.
There is, however, no guarantee that this wish can be fulfilled.<br>
</div>
<pre><span id="VALmemory_unmap_file"><span class="keyword">val</span> memory_unmap_file</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> unit</code></pre><div class="info">
Unmaps the file. The memory block must have been allocated
with <code class="code">memory_map_file</code> or with <code class="code">Bigarray.Array1.map_file</code>.
<p>
<b>Note that the data pointer of the bigarray is set to NULL,
and that any further access of the array will trigger a
segmentation violation!</b> The intention of this function is to
control when the file mapping is removed. Normally, this is
done first when the GC finalizer is run.
<p>
It is required that there are no subarrays at the time of
calling this function. (If so, the function does nothing.)<br>
</div>
<pre><span id="VALzero_pages"><span class="keyword">val</span> zero_pages</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> unit</code></pre><div class="info">
<code class="code">zero_pages m pos len</code>: If possible, the memory pages in the
range <code class="code">pos</code> to <code class="code">pos+len-1</code> of <code class="code">m</code> are allocated again, so that
they replace the previous pages.
<p>
It is required that the start address of the range is a
multiple of the page size, and the <code class="code">len</code> is a multiple of
the page size. Fails with <code class="code">Invalid_argument</code> if the requirements
are not met, or the function is otherwise unavailable.
<p>
Calling <code class="code">zero_pages</code> is sometimes an optimization when old
memory pages can be dropped, and when the alternative of
overwriting these pages would imply a copy-on-write operation.<br>
</div>
<pre><span id="VALgrab"><span class="keyword">val</span> grab</span> : <code class="type">nativeint -> int -> <a href="Netsys_mem.html#TYPEmemory">memory</a></code></pre><div class="info">
<code class="code">grab addr len</code>: Interprets the address range from <code class="code">addr</code> to
<code class="code">addr+len-1</code> as <code class="code">memory</code> bigarray.
<p>
This function does not allocate! It assumes that the given
address range points to valid memory.<br>
</div>
<br>
<h2 id="2_Interpretingmemoryasvalues">Interpreting memory as values</h2><br>
<pre><span id="VALas_value"><span class="keyword">val</span> as_value</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> 'a</code></pre><div class="info">
<code class="code">as_value mem offset</code>: Returns a pointer to <code class="code">mem+offset</code>. There
must be a valid boxed value at this address (i.e. at
the word preceding <code class="code">mem+offset</code> there must be a valid block
header, followed by a valid value of the right type). However,
this is not checked:
<p>
<b>This is an unsafe function that may crash the program if used
in the wrong way!</b>
<p>
It is possible that the memory block is deallocated while the
returned value still exists. Any attempt to access the value will
result into undefined behavior (anything from funny results
to crashes may happen).
<p>
Some Ocaml primitives might not work on the returned values
(polymorphic equality, marshalling, hashing) unless
<a href="Netsys_mem.html#VALvalue_area"><code class="code">Netsys_mem.value_area</code></a> is called for the memory block.<br>
</div>
<pre><span id="VALas_obj"><span class="keyword">val</span> as_obj</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> Obj.t</code></pre><div class="info">
Same as <code class="code">as_value</code> but returns the value as <code class="code">Obj.t</code><br>
</div>
<pre><span id="VALvalue_area"><span class="keyword">val</span> value_area</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> unit</code></pre><div class="info">
Marks the memory block as value area. This enables that the
value primitives (polymorphic equality, marshalling, hashing)
return meaningful results. The memory area is automatically
unmarked when the finaliser for the memory block is run.
<p>
Be careful when marking sub arrays.
<p>
This function is first available since O'Caml 3.11.<br>
</div>
<pre><span id="VALobj_address"><span class="keyword">val</span> obj_address</span> : <code class="type">Obj.t -> nativeint</code></pre><pre><span id="VALhdr_address"><span class="keyword">val</span> hdr_address</span> : <code class="type">Obj.t -> nativeint</code></pre><div class="info">
These two functions return the address of the <code class="code">Obj.t</code> and the
address of the header of the <code class="code">Obj.t</code>, respectively.
<p>
Note that this can only be relied upon if the input object
cannot be moved around by the garbage collector!<br>
</div>
<pre><span id="VALcmp_string"><span class="keyword">val</span> cmp_string</span> : <code class="type">string -> string -> int</code></pre><div class="info">
Compares two strings like <code class="code">String.compare</code>. This also works
when the strings reside outside the O'Caml heap, e.g. in a
<code class="code">memory</code> block.<br>
</div>
<pre><span id="EXCEPTIONOut_of_space"><span class="keyword">exception</span> Out_of_space</span></pre>
<pre><span id="VALinit_header"><span class="keyword">val</span> init_header</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> int -> unit</code></pre><div class="info">
<code class="code">init_header mem offset tag size</code>: Initializes the word at
<code class="code">mem+offset</code> as an Ocaml value header with the given <code class="code">tag</code>
and the given <code class="code">size</code> (in words). The GC color is always set
to "white".<br>
</div>
<pre><span id="VALinit_string"><span class="keyword">val</span> init_string</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> int * int</code></pre><div class="info">
<code class="code">let voffset, bytelen = init_string mem offset len</code>:
Initializes the memory at <code class="code">offset</code>
and following bytes as Ocaml string with length <code class="code">len</code>.
Returns in <code class="code">voffset</code> the offset where the value starts
(i.e. <code class="code">offset</code> plus one word), and in <code class="code">bytelen</code> the number
of bytes used in <code class="code">mem</code>.
<p>
<code class="code">offset</code> must be a multiple of the word size in bytes.
<p>
The string can be accessed with
<pre class="codepre"><code class="code"> let s = (as_value mem voffset : string) </code></pre>
<p>
The function is useful for initializing shared memory as string
so that several processes can directly access the string.
<p>
The string has the GC color <code class="code">White</code>.
<p>
Raises <code class="code">Out_of_space</code> if the memory block is too small.<br>
</div>
<pre><span id="VALinit_string_bytelen"><span class="keyword">val</span> init_string_bytelen</span> : <code class="type">int -> int</code></pre><div class="info">
Returns <code class="code">bytelen</code> if <code class="code">init_string</code> was called with the passed
<code class="code">len</code>.<br>
</div>
<pre><span id="VALinit_array"><span class="keyword">val</span> init_array</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> int * int</code></pre><div class="info">
<code class="code">let voffset, bytelen = init_array mem offset size</code>:
Initializes the memory at <code class="code">offset</code>
and following bytes as Ocaml array with <code class="code">size</code> elements.
Returns in <code class="code">voffset</code> the offset where the value starts
(i.e. <code class="code">offset</code> plus one word), and in <code class="code">bytelen</code> the number
of bytes used in <code class="code">mem</code>.
<p>
The array cannot be used as float array.
<p>
<code class="code">offset</code> must be a multiple of the word size in bytes.
<p>
The array can be accessed with
<pre class="codepre"><code class="code"> let a = (as_value mem voffset : _ array) </code></pre>
<p>
The elements of the array have a value but it might not be
valid for the element type of the array. Because of this, it
is unwise to access the elements before setting them for the
first time.
<p>
The array has the GC color <code class="code">White</code>.
<p>
Raises <code class="code">Out_of_space</code> if the memory block is too small.<br>
</div>
<pre><span id="VALinit_float_array"><span class="keyword">val</span> init_float_array</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> int * int</code></pre><div class="info">
Same for arrays of floats<br>
</div>
<pre><span id="VALinit_array_bytelen"><span class="keyword">val</span> init_array_bytelen</span> : <code class="type">int -> int</code></pre><div class="info">
Returns <code class="code">bytelen</code> if <code class="code">init_array</code> was called with the passed
<code class="code">size</code>.<br>
</div>
<pre><span id="VALinit_float_array_bytelen"><span class="keyword">val</span> init_float_array_bytelen</span> : <code class="type">int -> int</code></pre><div class="info">
Same for arrays of floats<br>
</div>
<pre><span id="TYPEcustom_ops"><span class="keyword">type</span> <code class="type"></code>custom_ops</span> = <code class="type">nativeint</code> </pre>
<pre><code><span id="TYPEinit_value_flag"><span class="keyword">type</span> <code class="type"></code>init_value_flag</span> = </code></pre><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTinit_value_flag.Copy_bigarray"><span class="constructor">Copy_bigarray</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTinit_value_flag.Copy_custom_int"><span class="constructor">Copy_custom_int</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTinit_value_flag.Copy_atom"><span class="constructor">Copy_atom</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTinit_value_flag.Copy_simulate"><span class="constructor">Copy_simulate</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTinit_value_flag.Copy_conditionally"><span class="constructor">Copy_conditionally</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTinit_value_flag.Keep_atom"><span class="constructor">Keep_atom</span></span></code></td>
</tr></table>
<pre><span id="VALinit_value"><span class="keyword">val</span> init_value</span> : <code class="type">?targetaddr:nativeint -><br> ?target_custom_ops:(string * <a href="Netsys_mem.html#TYPEcustom_ops">custom_ops</a>) list -><br> ?cc:(nativeint * nativeint) list -><br> <a href="Netsys_mem.html#TYPEmemory">memory</a> -><br> int -> 'a -> <a href="Netsys_mem.html#TYPEinit_value_flag">init_value_flag</a> list -> int * int</code></pre><div class="info">
<code class="code">let voffset, bytelen = init_value mem offset v flags</code>:
Initializes the memory at <code class="code">offset</code> and following bytes as
copy of the boxed value <code class="code">v</code>.
Returns in <code class="code">voffset</code> the offset where the value starts
(i.e. <code class="code">offset</code> plus one word), and in <code class="code">bytelen</code> the number
of bytes used in <code class="code">mem</code>.
<p>
The copied value can then be accessed with
<pre class="codepre"><code class="code"> let v' = (as_value mem voffset : 'a) </code></pre>
<p>
<code class="code">offset</code> must be a multiple of the word size in bytes.
<p>
The input value <code class="code">v</code> must be heap-allocated. Also, a number of
restrictions and caveats apply:<ul>
<li>Objects, closures, and lazy values are not supported</li>
<li>Bigarrays are only supported if the <code class="code">Copy_bigarray</code> flag
is given. In this case, a copy of the bigarray is also made
and appended to the value copy (i.e. it is also placed into
the buffer <code class="code">mem</code>).</li>
<li>Abstract and custom values need to be enabled. For
<code class="code">int32</code>, <code class="code">int64</code>, and <code class="code">nativeint</code> the flag <code class="code">Copy_custom_int</code>
enables copying, and for bigarrays the flag <code class="code">Copy_bigarray</code>.
Generally, there is a function pointer in such data blocks which
might be invalid when the memory buffer is loaded into a
different executable. This specific problem can be fixed
by passing <code class="code">target_custom_ops</code> with the right pointers.</li>
<li>Atoms (i.e. zero-sized blocks such as empty arrays) are only
supported if the <code class="code">Copy_atom</code> or <code class="code">Keep_atom</code> flags are present,
otherwise the function fails. <code class="code">Keep_atom</code> means here to keep
atoms as-is. This is correct, but also keeps references to
the atom definitions which live outside <code class="code">mem</code>. <code class="code">Copy_atom</code> means to
create a copy of the atom as a zero-sized block outside the
atom table. This way the value in <code class="code">mem</code> is self-contained,
but this unfortunately breaks some assumptions of the
OCaml code generator. In particular, comparisons like
<code class="code">if array=[| |] then...</code> may yield wrong results.</li>
<li>The input value may reside outside the Ocaml heap. This may break
badly written C wrappers that do not use abstract or custom
tags to mark foreign data.</li>
</ul>
The function raises <code class="code">Out_of_space</code> if the memory block is too small.
Cyclic input values are supported, and value sharing is kept intact.
<p>
If the <code class="code">Copy_simulate</code> flag is given, <code class="code">mem</code> is not modified.
In simulation mode, it is pretended that <code class="code">mem</code> is as large
as necessary to hold the value, no matter how large <code class="code">mem</code> really
is. The returned values <code class="code">voffset</code> and <code class="code">bytelen</code> reflect how much
of <code class="code">mem</code> would have been used.
<p>
If the <code class="code">targetaddr</code> argument is passed, it is assumed that the
memory block is mapped at this address and not at the address it
is really mapped. This is useful for preparing memory that is going
to be mapped at a different address than it is right now.
<p>
The new value has the GC color <code class="code">White</code>.
<p>
If bigarrays are copied, the copy also includes the data part.
The data part is directly following the bigarray block, and is
represented in a special implementation-defined way.
<p>
If the <code class="code">Copy_conditionally</code> flag is set, the condition <code class="code">cc</code> is
evaluated for every block, and only if <code class="code">cc</code> returns true, the block
is copied. <code class="code">cc</code> is a list of addresses <code class="code">(start,end)</code>, and a block
is not copied if its address lies in any of these address ranges.
Otherwise the block is copied. As an exception of the foregoing,
the first block (i.e. <code class="code">v</code>) is always copied.<br>
</div>
<pre><span id="VALget_custom_ops"><span class="keyword">val</span> get_custom_ops</span> : <code class="type">'a -> string * <a href="Netsys_mem.html#TYPEcustom_ops">custom_ops</a></code></pre><div class="info">
Returns custom ops for a sample value (or <code class="code">Invalid_argument</code>)<br>
</div>
<pre><span id="VALcopy_value"><span class="keyword">val</span> copy_value</span> : <code class="type"><a href="Netsys_mem.html#TYPEinit_value_flag">init_value_flag</a> list -> 'a -> 'a</code></pre><div class="info">
<code class="code">copy_value flags v</code>: Creates a deep copy of <code class="code">v</code> and returns it.
The copy is allocated in the normal Ocaml heap.
<p>
Restrictions:<ul>
<li>Objects, closures, and lazy values are not supported (FIXME)</li>
<li>Bigarrays are only supported if the <code class="code">Copy_bigarray</code> flag
is given. In this case, a copy of bigarrays are also made,
and placed into additional buffers obtained via <code class="code">stat_alloc</code>.</li>
<li>Abstract and custom values need to be enabled. For
<code class="code">int32</code>, <code class="code">int64</code>, and <code class="code">nativeint</code> the flag <code class="code">Copy_custom_int</code>
enables copying, and for bigarrays the flag <code class="code">Copy_bigarray</code>.</li>
<li>Atoms are automatically fixed. <code class="code">Copy_atoms</code> is ignored.</li>
</ul>
Cyclic input values are supported. <code class="code">Copy_simulate</code> is ignored.<br>
</div>
<pre><code><span id="TYPEcolor"><span class="keyword">type</span> <code class="type"></code>color</span> = </code></pre><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTcolor.White"><span class="constructor">White</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTcolor.Gray"><span class="constructor">Gray</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTcolor.Blue"><span class="constructor">Blue</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTcolor.Black"><span class="constructor">Black</span></span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >GC colors</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>
<pre><span id="VALcolor"><span class="keyword">val</span> color</span> : <code class="type">Obj.t -> <a href="Netsys_mem.html#TYPEcolor">color</a></code></pre><div class="info">
Return the GC color<br>
</div>
<pre><span id="VALset_color"><span class="keyword">val</span> set_color</span> : <code class="type">Obj.t -> <a href="Netsys_mem.html#TYPEcolor">color</a> -> unit</code></pre><div class="info">
Set the GC color<br>
</div>
<pre><span id="VALis_bigarray"><span class="keyword">val</span> is_bigarray</span> : <code class="type">Obj.t -> bool</code></pre><div class="info">
Checks whether the objects ia actually a bigarray<br>
</div>
<br>
<h2 id="2_IOusingmemoryasbuffers">I/O using <code class="code">memory</code> as buffers</h2><br>
<pre><span id="VALmem_read"><span class="keyword">val</span> mem_read</span> : <code class="type">Unix.file_descr -> <a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> int</code></pre><div class="info">
A version of <code class="code">Unix.read</code> that uses a <code class="code">memory</code> buffer.
Some OS allow faster I/O when <code class="code">memory</code> is page-aligned
(see <code class="code">alloc_memory_pages</code>). Also, a copy in the stub function
can be avoided. Both effects can result in a considerable speedup.<br>
</div>
<pre><span id="VALmem_write"><span class="keyword">val</span> mem_write</span> : <code class="type">Unix.file_descr -> <a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> int</code></pre><div class="info">
A version of <code class="code">Unix.single_write</code> that uses a <code class="code">memory</code> buffer.<br>
</div>
<pre><span id="VALmem_recv"><span class="keyword">val</span> mem_recv</span> : <code class="type">Unix.file_descr -><br> <a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> Unix.msg_flag list -> int</code></pre><pre><span id="VALmem_send"><span class="keyword">val</span> mem_send</span> : <code class="type">Unix.file_descr -><br> <a href="Netsys_mem.html#TYPEmemory">memory</a> -> int -> int -> Unix.msg_flag list -> int</code></pre><div class="info">
Versions of <code class="code">Unix.recv</code>, and <code class="code">Unix.send</code>
using <code class="code">memory</code> buffers.<br>
</div>
<br>
<h2 id="2_Bufferpools">Buffer pools</h2><br>
<pre><span id="TYPEmemory_pool"><span class="keyword">type</span> <code class="type"></code>memory_pool</span> </pre>
<div class="info">
A pool of <code class="code">memory</code> blocks that are all the same size and page-aligned
(if the OS supports this). The pool tries to bundle memory allocations
so that not for every block a system call is required. This reduces
the number of system calls, and the number of entries in the process
page table. Also, unused blocks are automatically returned to the
pool.<br>
</div>
<pre><span id="VALcreate_pool"><span class="keyword">val</span> create_pool</span> : <code class="type">int -> <a href="Netsys_mem.html#TYPEmemory_pool">memory_pool</a></code></pre><div class="info">
Create a new pool. The argument is the size of the memory blocks
(must be a multiple of the page size)<br>
</div>
<pre><span id="VALpool_alloc_memory"><span class="keyword">val</span> pool_alloc_memory</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory_pool">memory_pool</a> -> <a href="Netsys_mem.html#TYPEmemory">memory</a></code></pre><div class="info">
<code class="code">let m = pool_alloc_memory p</code>:
Gets a memory block <code class="code">m</code> from the pool <code class="code">p</code>. If required, new blocks are
automatically allocated and added to the pool. This function is
thread-safe.
<p>
The memory block is automatically garbage-collected.<br>
</div>
<pre><span id="VALpool_alloc_memory2"><span class="keyword">val</span> pool_alloc_memory2</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory_pool">memory_pool</a> -> <a href="Netsys_mem.html#TYPEmemory">memory</a> * (unit -> unit)</code></pre><div class="info">
<code class="code">let m, free = pool_alloc_memory2 p</code>:
Gets a memory block <code class="code">m</code> from the pool <code class="code">p</code> like <code class="code">pool_alloc_memory</code>.
This function also returns the function <code class="code">free</code> marking the
block as free again. The block can then be immediately recycled
for another use.
<p>
If <code class="code">free</code> is not called, the block <code class="code">m</code> is first recycled when it
is not referenced any more (like in <code class="code">pool_alloc_memory</code>).<br>
</div>
<pre><span id="VALpool_reclaim"><span class="keyword">val</span> pool_reclaim</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory_pool">memory_pool</a> -> unit</code></pre><div class="info">
Reclaim as much memory as possible<br>
</div>
<pre><span id="VALpool_block_size"><span class="keyword">val</span> pool_block_size</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory_pool">memory_pool</a> -> int</code></pre><div class="info">
Returns the size of the memory blocks in bytes<br>
</div>
<pre><span id="VALdefault_block_size"><span class="keyword">val</span> default_block_size</span> : <code class="type">int</code></pre><div class="info">
The default block size, normally 64 K (or better, 16 times the
page size)<br>
</div>
<pre><span id="VALdefault_pool"><span class="keyword">val</span> default_pool</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory_pool">memory_pool</a></code></pre><div class="info">
The default pool with the default block size. This pool is used
by Ocamlnet itself as much as possible<br>
</div>
<pre><span id="VALsmall_block_size"><span class="keyword">val</span> small_block_size</span> : <code class="type">int</code></pre><div class="info">
The block size of <code class="code">small_pool</code>, normally 4K (or better, the
page size)<br>
</div>
<pre><span id="VALsmall_pool"><span class="keyword">val</span> small_pool</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory_pool">memory_pool</a></code></pre><div class="info">
Another standard pool where the blocks are smaller than in
<code class="code">default_pool</code>.<br>
</div>
<pre><span id="VALpool_report"><span class="keyword">val</span> pool_report</span> : <code class="type"><a href="Netsys_mem.html#TYPEmemory_pool">memory_pool</a> -> string</code></pre><div class="info">
Returns a report describing the memory allocation in the pool<br>
</div>
</body></html>
