module Netshm:sig
..end
type
shm_descr
typeshm_type =
[ `File | `POSIX ]
val supported_types : shm_type list
typeshm_name =
[ `File of string | `POSIX of string * string ]
shm_name
is a name for a shared memory object.val shm_type_of_name : shm_name -> shm_type
val open_shm : ?unique:bool ->
shm_name -> Unix.open_flag list -> int -> shm_descr
For POSIX_shm
not all open flags can be specified. The flags
are limited to O_RDONLY
, O_RDWR
, O_CREAT
, O_EXCL
and
O_TRUNC
.
unique
: Unique file generation as in create_unique_shm
.
val create_unique_shm : shm_name -> int -> shm_descr
shm_name
. The actual name can be queried with
name_of_shm
(below).
For POSIX
and File
names, deriving works by replacing
the 'X' letters in the file name by random digits and letters.
For example, if the name is File "/my/directory/ocaml.XXXXXX"
six random characters are generated and replace the 'X' letters
such that the file is unique.
The integer is the file permission.
val name_of_shm : shm_descr -> shm_name
val close_shm : shm_descr -> unit
val unlink_shm : shm_name -> unit
val chmod_shm : shm_descr -> int -> unit
val chown_shm : shm_descr -> int -> int -> unit
typelocking_method =
[ `No_locking | `Record_locking ]
No_locking
is selected, such protection is not done - this
is ok if only read accesses occur or if the user can ensure that
never a write access is done in parallel with another access.
The locking method must be compatible with the type of shared memory.val best_locking_method : shm_type -> locking_method
No_locking
int32
as key and one-dimensional int32
bigarray as values.Hashtbl
of stdlibtype
shm_table
typeint32_array =
(int32, Bigarray.int32_elt, Bigarray.c_layout) Bigarray.Array1.t
exception Corrupt_file of string
exception Deadlock
group
function is usedval manage : ?pagesize:int ->
?init:int -> locking_method -> shm_descr -> shm_table
shm_table
. If
the object is empty, it is automatically enlarged to the
minimum size and initialized. If the object is non-empty it is
expected that it already contains a valid shm_table
structure.
The object automatically grows in size when new elements are
added to the object. By removing elements, however, the
object is never shrinked. Unused memory is held back for later
reallocation by the same shm_table
.
By default, the table uses a page size of 256 bytes. The page size is
the unit of memory allocation. The parameter pagesize
overrides
this default. The page size must be at least 160 and divisible by 4.
The page size must be the same when the table was created.
By passing init
it is enforced that the table is re-initialized
(deleted and again created). The argument of init
is a hint
for the number of elements the table will contain. The data
structure is then created such that this many elements can be added
without needing expensive data reorganization.
Special note for using shm_table
with multiple processes: Every
process must create its own shm_descr
, and every process must
call manage
to manage it. It is not sufficient to just fork
a new process, and to keep using the already existing
shm_descr
or shm_table
in the subprocess. (This doesn't work
because the underlying file descriptor would be shared.)
val group : shm_table -> ('a -> 'b) -> 'a -> 'b
let r =
group table
(fun arg ->
operation1; operation2; ...)
arg
Operations can be any reading or writing functions from below. The effect is that the locking requirements of the operations are merged, so that no operation of another process can interfer with the grouped sequence. Note, however, that this gives no real atomicity as there is no way to roll back half-executed sequences.
Groups can be nested.
An example of group
is to set a binding depending on the previous
value of the binding. Here, we add 1:
let add_one table =
group table
(fun key ->
let ba =
try find table key
with Not_found ->
Bigarray.Array1.create Bigarray.int32 Bigarray.c_layout 1 in
ba.{ 0 } <- Int32.succ ba.{ 0 };
replace table key ba
)
Grouping protects the update from modifications done by other processes
at the same time. In particular, without grouping it can happen that
another process also modifies the same value between find
and
replace
.
val add : shm_table -> int32 -> int32_array -> unit
add tbl key value
: Adds the binding of key
to value
to the
table. Previous bindings are not removed, but simply hidden.val find : shm_table -> int32 -> int32_array
find tbl key
: Finds the current binding of key
in tbl
or
raises Not_found
if no such binding exists.val find_all : shm_table -> int32 -> int32_array list
find_all tbl key
returns the list of all data
associated with key
in tbl
.
The current binding is returned first, then the previous
bindings, in reverse order of introduction in the table.val mem : shm_table -> int32 -> bool
mem tbl key
checks if key
is bound in tbl
.val remove : shm_table -> int32 -> unit
remove tbl key
removes the current binding of key
in tbl
,
restoring the previous binding if it exists.
It does nothing if key
is not bound in tbl
.val replace : shm_table -> int32 -> int32_array -> unit
replace tbl key value
replaces the current binding of key
in tbl
by a binding of key
to value
. If key
is unbound in tbl
,
a binding of key
to value
is added to tbl
.val iter : (int32 -> int32_array -> unit) -> shm_table -> unit
iter f tbl
applies f
to all bindings in table tbl
.
f
receives the key as first argument, and the associated value
as second argument. Each binding is presented exactly once to f
.
The order in which the bindings are passed to f
is unspecified.
However, if the table contains several bindings for the same key,
they are passed to f
in reverse order of introduction, that is,
the most recent binding is passed first.
While the iteration is in progress, the table is read-locked.
That means you cannot modify it during the iteration.
val iter_keys : (int32 -> unit) -> shm_table -> unit
iter_keys f tbl
applies f
to all keys in table tbl
. If there
are several bindings for a key, f
is only called once.
While the iteration is in progress, the table is locked.
That means you cannot modify it during the iteration.
val fold : (int32 -> int32_array -> 'a -> 'a) -> shm_table -> 'a -> 'a
fold f tbl init
computes
(f kN dN ... (f k1 d1 init)...)
,
where k1 ... kN
are the keys of all bindings in tbl
,
and d1 ... dN
are the associated values.
Each binding is presented exactly once to f
.
The order in which the bindings are passed to f
is unspecified.
However, if the table contains several bindings for the same key,
they are passed to f
in reverse order of introduction, that is,
the most recent binding is passed first.
While the iteration is in progress, the table is locked.
That means you cannot modify it during the iteration.
val length : shm_table -> int
length tbl
returns the number of bindings in tbl
.
Multiple bindings are counted multiply, so length
gives the number of times iter
calls its first argument.exception Next
exception Break
val read_blocks : shm_table -> int32 -> (int32_array option -> unit) -> unit
find_blocks tbl key f
: The values may be stored in several
disk blocks. This interface allows one to access the values block by
block. As find_all
, all bindings for key
in tbl
are determined
in reverse order, i.e. the newest binding first, the oldest last.
For every binding value
, the function f
is invoked in a sequence
f (Some v1)
, f (Some v2)
, ..., f (Some vN)
, f None
where
value
is the array concatenation of v1
, v2
, ..., vN
.
The function f
may raise the exception Next
to go
directly to the start of the next binding of key
.
The exception Break
stops the iteration immediately.
Note that the int32_array
fragments vK
point to shared memory.
Any assignment would modify the shared memory object directly!
The binding is at that time, however, only read-locked, so this
should be avoided.
typewrite_op =
[ `Remove_binding ]
typectrl_op =
[ `Nop | `Remove_binding ]
val write_blocks : shm_table ->
write_op list ->
int32 -> (int32_array option -> ctrl_op) -> unit
write_blocks tbl ops key f
: Like read_blocks
this function iterates
over the blocks of all bindings for key
. For every binding value
,
the function f
is invoked in a sequence
f (Some v1)
, f (Some v2)
, ..., f (Some vN)
, f None
.
Unlike read_blocks
the function f
returns a value.
The last non-`Nop
result value in this sequence determines the
modification to carry out for the binding:
`Remove_binding
: The whole binding is removed from the table.f
just return `Nop
, no further modification
is done.
The modifications must be announced in the ops
argument. It is
not allowed that f
returns a value not being a member of ops
(except `Nop
).
It is possible to raise the special exceptions Next
and Break
just as for read_blocks
.
Note that the int32_array
fragments vK
point to shared memory.
Any assignment will modify the shared memory object directly!
The binding is at that time write-locked, so such assignments
are protected against concurrent writes.
val dump : shm_table -> unit
val bigarray : int array -> int32_array
val memory : shm_table ->
(int32, Bigarray.int32_elt, Bigarray.c_layout) Bigarray.Array2.t