Up  Next

Module Pool_intf.Pool.Obj_array

module Obj_array: S  with type 'a Pointer.t = private int
Obj_array is an efficient implementation of pools that uses a single chunk of memory, and is what an application should ultimately use. We expose that Pointer.t is an int so that OCaml can avoid the write barrier, due to knowing that Pointer.t isn't an OCaml pointer.
module Slots: Tuple_type.Slots 
module Slot: Tuple_type.Slot 
module Pointer: sig .. end
type 'slots t
The type of a pool. 'slots will look like ('a1, ..., 'an) Slots.tn, and the pool holds tuples of type 'a1 * ... * 'an.
include Invariant.S1
val pointer_is_valid : 'slots t -> 'slots Pointer.t -> bool
pointer_is_valid t pointer returns true iff pointer points to a tuple in t, i.e. pointer is not null, not free, and is in the range of t.

A pointer might not be in the range of a pool if it comes from another pool for example. In this case unsafe_get/set functions would cause a segfault.

val id_of_pointer : 'slots t -> 'slots Pointer.t -> int
id_of_pointer t pointer is an integer which is unique for the lifetime of a tuple in the pool. When the tuple is freed, the identifier may be reused for another pointer.
val pointer_of_id : 'slots t ->
       int -> 'slots Pointer.t Core.Std.Or_error.t
pointer_of_id t pointer returns the pointer with this identifier. It returns Error _ if id does not correspond to any pointer in this pool. pointer_of_id does not guarantee that the resulting pointer satisfies pointer_is_valid because the tuple may not be in use.
val create : ('tuple, 'a) Slots.t ->
       capacity:int -> dummy:'tuple -> ('tuple, 'a) Slots.t t
create slots ~capacity ~dummy creates an empty pool that can hold up to capacity N-tuples. The slots of dummy are stored in free tuples.
val capacity : 'a t -> int
capacity returns the maximum number of tuples that the pool can hold.
val length : 'a t -> int
length returns the number of tuples currently in the pool. 

        0 <= length t <= capacity t
      

val grow : ?capacity:int -> 'a t -> 'a t
grow t ~capacity returns a new pool t' with the supplied capacity. The new pool is to be used as a replacement for t. All live tuples in t are now live in t', and valid pointers to tuples in t are now valid pointers to the identical tuple in t'. It is an error to use t after calling grow t.

grow raises if the supplied capacity isn't larger than capacity t.

val is_full : 'a t -> bool
is_full t returns true if no more tuples can be allocated in t.
val free : 'slots t -> 'slots Pointer.t -> unit
free t pointer frees the tuple pointed to by pointer from t.
val new1 : 'a0 Slots.t1 t -> 'a0 -> 'a0 Slots.t1 Pointer.t
new<N> t a0 ... a<N-1> returns a new tuple from the pool, with the tuple's slots initialized to a0 ... a<N-1>. new raises if is_full t.
val new2 : ('a0, 'a1) Slots.t2 t ->
       'a0 -> 'a1 -> ('a0, 'a1) Slots.t2 Pointer.t
val new3 : ('a0, 'a1, 'a2) Slots.t3 t ->
       'a0 -> 'a1 -> 'a2 -> ('a0, 'a1, 'a2) Slots.t3 Pointer.t
val new4 : ('a0, 'a1, 'a2, 'a3) Slots.t4 t ->
       'a0 ->
       'a1 -> 'a2 -> 'a3 -> ('a0, 'a1, 'a2, 'a3) Slots.t4 Pointer.t
val new5 : ('a0, 'a1, 'a2, 'a3, 'a4) Slots.t5 t ->
       'a0 ->
       'a1 ->
       'a2 -> 'a3 -> 'a4 -> ('a0, 'a1, 'a2, 'a3, 'a4) Slots.t5 Pointer.t
val new6 : ('a0, 'a1, 'a2, 'a3, 'a4, 'a5) Slots.t6 t ->
       'a0 ->
       'a1 ->
       'a2 ->
       'a3 ->
       'a4 -> 'a5 -> ('a0, 'a1, 'a2, 'a3, 'a4, 'a5) Slots.t6 Pointer.t
val new7 : ('a0, 'a1, 'a2, 'a3, 'a4, 'a5, 'a6) Slots.t7 t ->
       'a0 ->
       'a1 ->
       'a2 ->
       'a3 ->
       'a4 ->
       'a5 ->
       'a6 -> ('a0, 'a1, 'a2, 'a3, 'a4, 'a5, 'a6) Slots.t7 Pointer.t
val new8 : ('a0, 'a1, 'a2, 'a3, 'a4, 'a5, 'a6, 'a7) Slots.t8 t ->
       'a0 ->
       'a1 ->
       'a2 ->
       'a3 ->
       'a4 ->
       'a5 ->
       'a6 ->
       'a7 ->
       ('a0, 'a1, 'a2, 'a3, 'a4, 'a5, 'a6, 'a7) Slots.t8 Pointer.t
val new9 : ('a0, 'a1, 'a2, 'a3, 'a4, 'a5, 'a6, 'a7, 'a8) Slots.t9 t ->
       'a0 ->
       'a1 ->
       'a2 ->
       'a3 ->
       'a4 ->
       'a5 ->
       'a6 ->
       'a7 ->
       'a8 ->
       ('a0, 'a1, 'a2, 'a3, 'a4, 'a5, 'a6, 'a7, 'a8) Slots.t9 Pointer.t
val get_tuple : ('tuple, 'a) Slots.t t ->
       ('tuple, 'a) Slots.t Pointer.t -> 'tuple
get_tuple t pointer allocates an OCaml tuple isomorphic to the pool t's tuple pointed to by pointer.
val get : ('a, 'variant) Slots.t t ->
       ('a, 'variant) Slots.t Pointer.t ->
       ('variant, 'slot) Slot.t -> 'slot
get t pointer slot gets slot of the tuple pointed to by pointer in pool t. In the usual way with manual memory management, it is an error to refer to a pointer that has been freed. It is also an error to use a pointer with any pool other than the one the pointer was new'd from or grown to.

unsafe_get is like get, but skips bounds checking, and can thus segfault. unsafe_get is comparable in speed to get for immediate values, and 5%-10% faster for pointers. Since the difference is so small, one should as usual be very convinced of the speed benefit before using these and introducing the possibility of segfaults.

val unsafe_get : ('a, 'variant) Slots.t t ->
       ('a, 'variant) Slots.t Pointer.t ->
       ('variant, 'slot) Slot.t -> 'slot
val set : ('a, 'variant) Slots.t t ->
       ('a, 'variant) Slots.t Pointer.t ->
       ('variant, 'slot) Slot.t -> 'slot -> unit
set t pointer slot a sets to a the slot of the tuple pointed to by pointer in pool t. In the usual way with manual memory management, it is an error to refer to a pointer that has been freed. It is also an error to use a pointer with any pool other than the one the pointer was new'd from or grown to.

unsafe_set is like set, but skips bounds checking, and can thus segfault.

val unsafe_set : ('a, 'variant) Slots.t t ->
       ('a, 'variant) Slots.t Pointer.t ->
       ('variant, 'slot) Slot.t -> 'slot -> unit
val sexp_of_t : ('slots -> Sexplib.Sexp.t) -> 'slots t -> Sexplib.Sexp.t

pointer_is_valid t pointer returns true iff pointer points to a tuple in t, i.e. pointer is not null, not free, and is in the range of t.

A pointer might not be in the range of a pool if it comes from another pool for example. In this case unsafe_get/set functions would cause a segfault.

id_of_pointer t pointer is an integer which is unique for the lifetime of a tuple in the pool. When the tuple is freed, the identifier may be reused for another pointer.

pointer_of_id t pointer returns the pointer with this identifier. It returns Error _ if id does not correspond to any pointer in this pool. pointer_of_id does not guarantee that the resulting pointer satisfies pointer_is_valid because the tuple may not be in use.

create slots ~capacity ~dummy creates an empty pool that can hold up to capacity N-tuples. The slots of dummy are stored in free tuples.

capacity returns the maximum number of tuples that the pool can hold.

length returns the number of tuples currently in the pool. 

        0 <= length t <= capacity t


grow t ~capacity returns a new pool t' with the supplied capacity. The new pool is to be used as a replacement for t. All live tuples in t are now live in t', and valid pointers to tuples in t are now valid pointers to the identical tuple in t'. It is an error to use t after calling grow t.

grow raises if the supplied capacity isn't larger than capacity t.

default is 2 * capacity t

is_full t returns true if no more tuples can be allocated in t.

free t pointer frees the tuple pointed to by pointer from t.

new<N> t a0 ... a<N-1> returns a new tuple from the pool, with the tuple's slots initialized to a0 ... a<N-1>. new raises if is_full t.

get_tuple t pointer allocates an OCaml tuple isomorphic to the pool t's tuple pointed to by pointer.

get t pointer slot gets slot of the tuple pointed to by pointer in pool t. In the usual way with manual memory management, it is an error to refer to a pointer that has been freed. It is also an error to use a pointer with any pool other than the one the pointer was new'd from or grown to.

unsafe_get is like get, but skips bounds checking, and can thus segfault. unsafe_get is comparable in speed to get for immediate values, and 5%-10% faster for pointers. Since the difference is so small, one should as usual be very convinced of the speed benefit before using these and introducing the possibility of segfaults.

set t pointer slot a sets to a the slot of the tuple pointed to by pointer in pool t. In the usual way with manual memory management, it is an error to refer to a pointer that has been freed. It is also an error to use a pointer with any pool other than the one the pointer was new'd from or grown to.

unsafe_set is like set, but skips bounds checking, and can thus segfault.