module Netsys_mem:Bigarrays as memory bufferssig
..end
typememory =
Netsys_types.memory
val blit_memory_to_string : memory -> int -> string -> int -> int -> unit
blit_memory_to_string src srcoff dst dstoff len
copies len
characters
from buffer src
, starting at character number srcoff
, to
string dst
, starting at character number dstoff
Raise Invalid_argument
if srcoff
and len
do not
designate a valid subbuffer of src
, or if dstoff
and len
do not designate a valid substring of dst
.
val blit_string_to_memory : string -> int -> memory -> int -> int -> unit
blit_string_to_memory src srcoff dst dstoff len
copies len
characters
from string src
, starting at character number srcoff
, to
buffer dst
, starting at character number dstoff
Raise Invalid_argument
if srcoff
and len
do not
designate a valid substring of src
, or if dstoff
and len
do not designate a valid subbuffer of dst
.
val memory_address : memory -> nativeint
val getpagesize : unit -> int
On many systems, a page has 4096 bytes, but this cannot be relied upon.
This function is only available if the system has sysconf
.
val alloc_memory_pages : ?addr:nativeint -> int -> memory
The passed int is the requested number of bytes. The size of the buffer is rounded up so a whole number of pages is allocated.
Optionally, one can request a certain address addr
(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
memory_address
what the start address really is.
This function is only available if the system has sysconf
, mmap
,
and allows to allocate anonymous memory with mmap
(outside POSIX
but common).
val alloc_aligned_memory : int -> int -> memory
alloc_aligned_memory alignment size
: Allocates a buffer of size
whose start address is a multiple of alignment
. The alignment
must be a power of two, and at least Sys.word_size/8
.
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 /proc/cpuinfo
.)
This function is only available if the system has posix_memalign
.
val memory_map_file : Unix.file_descr ->
?pos:int64 -> ?addr:nativeint -> bool -> int -> memory
memory_map_file fd shared size
: Maps size
bytes of the file
fd
into memory, and returns the memory buffer like
Bigarray.Array1.map_file
. pos
and shared
have the same
meaning as there. In addr
one can suggest a start address.
There is, however, no guarantee that this wish can be fulfilled.val memory_unmap_file : memory -> unit
memory_map_file
or with Bigarray.Array1.map_file
.
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! 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.
It is required that there are no subarrays at the time of
calling this function. (If so, the function does nothing.)
val zero_pages : memory -> int -> int -> unit
zero_pages m pos len
: If possible, the memory pages in the
range pos
to pos+len-1
of m
are allocated again, so that
they replace the previous pages.
It is required that the start address of the range is a
multiple of the page size, and the len
is a multiple of
the page size. Fails with Invalid_argument
if the requirements
are not met, or the function is otherwise unavailable.
Calling zero_pages
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.
val as_value : memory -> int -> 'a
as_value mem offset
: Returns a pointer to mem+offset
. There
must be a valid boxed value at this address (i.e. at
the word preceding mem+offset
there must be a valid block
header, followed by a valid value of the right type). However,
this is not checked:
This is an unsafe function that may crash the program if used in the wrong way!
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).
Some Ocaml primitives might not work on the returned values
(polymorphic equality, marshalling, hashing) unless
Netsys_mem.value_area
is called for the memory block.
val value_area : memory -> unit
Be careful when marking sub arrays.
This function is first available since O'Caml 3.11.
val cmp_string : string -> string -> int
String.compare
. This also works
when the strings reside outside the O'Caml heap, e.g. in a
memory
block.exception Out_of_space
val init_string : memory -> int -> int -> int * int
let voffset, bytelen = init_string mem offset len
:
Initializes the memory at offset
and following bytes as Ocaml string with length len
.
Returns in voffset
the offset where the value starts
(i.e. offset
plus one word), and in bytelen
the number
of bytes used in mem
.
offset
must be a multiple of the word size in bytes.
The string can be accessed with
let s = (as_value mem voffset : string)
The function is useful for initializing shared memory as string so that several processes can directly access the string.
Raises Out_of_space
if the memory block is too small.
val init_string_bytelen : int -> int
bytelen
if init_string
was called with the passed
len
.type
init_value_flag =
| |
Copy_bigarray |
| |
Copy_custom |
| |
Copy_atom |
| |
Copy_simulate |
val init_value : ?targetaddr:nativeint ->
memory ->
int -> 'a -> init_value_flag list -> int * int
let voffset, bytelen = init_value mem offset v flags
:
Initializes the memory at offset
and following bytes as
copy of the heap-allocated value v
.
Returns in voffset
the offset where the value starts
(i.e. offset
plus one word), and in bytelen
the number
of bytes used in mem
.
The copied value can then be accessed with
let v' = (as_value mem voffset : 'a)
offset
must be a multiple of the word size in bytes.
The input value v
must be heap-allocated. Also, a number of
restrictions and caveats apply:
Copy_bigarray
flag
is given. In this case, a copy of the bigarray is also made
and appended to the value copy. Memory-mapped bigarrays are
not supported.int32
, int64
, and nativeint
if the Copy_custom
is given, and except bigarrays if Copy_bigarray
is
given. There is a function pointer in such data blocks which
might be invalid when the memory buffer is loaded into a
different executable.Copy_atom
flag is present. It is, however,
illegal to copy atoms because they lose then their atomic
property. This breaks comparisons.Out_of_space
if the memory block is too small.
Cyclic input values are supported.
If the Copy_simulate
flag is given, mem
is not modified.
In simulation mode, it is pretended that mem
is as large
as necessary to hold the value, no matter how large mem
really
is. The returned values voffset
and bytelen
reflect how much
of mem
would have been used.
If the targetaddr
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.
memory
as buffersval mem_read : Unix.file_descr -> memory -> int -> int -> int
Unix.read
that uses a memory
buffer.
Some OS allow faster I/O when memory
is page-aligned
(see alloc_memory_pages
). Also, a copy in the stub function
can be avoided. Both effects can result in a considerable speedup.val mem_write : Unix.file_descr -> memory -> int -> int -> int
Unix.single_write
that uses a memory
buffer.val mem_recv : Unix.file_descr ->
memory -> int -> int -> Unix.msg_flag list -> int
val mem_send : Unix.file_descr ->
memory -> int -> int -> Unix.msg_flag list -> int
Unix.recv
, and Unix.send
using memory
buffers.type
memory_pool
memory
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.val create_pool : int -> memory_pool
val pool_alloc_memory : memory_pool -> memory
let (m,free) = pool_alloc_memory p
:
Gets a memory block m
from the pool p
. If required, new blocks are
automatically allocated and added to the pool. This function is
thread-safe.
The memory block is automatically garbage-collected.
val pool_block_size : memory_pool -> int
val default_pool : memory_pool
val pool_report : memory_pool -> string