# Module Netmcore_buffer

    module Netmcore_buffer: sig .. end

Shared buffer

One can add more data to the end of the buffer, and one can remove data from the beginning of the buffer.

Additions and deletions of data are atomic, and are strictly serialized. Read accesses can occur in parallel, and can even overlap with modifications (to some degree). It is, however, ensured that reads do not see the parallel modification, i.e. reads always base on the state from the beginning of the read operation.

It is not excluded that additions can be executed in parallel. If done this way, it is guaranteed that the effects of parallel additions are the same as if they were executed in a serial way. In particular, if an addition operation returns, this addition and all parallel additions affecting preceding index positions must be done. (The current implementation does not attempt this optimization.)

Index positions are "eternal", i.e. the index position of a byte does not change when preceding bytes are deleted. Instead, a deletion merely advances the start index of the valid data (which is not necessarily 0). This model is more consistent with parallel modifications.

On 32 bit platforms it can happen that index positions wrap around (at 1G). The position following `max_int` is 0. The length is restricted to `max_int-bsize` on these platforms.

    type 'a buffer

A buffer with a header of type `'h`

    type 'a buffer_descr

The marshallable buffer descriptor

    val create : Netmcore.res_id -> int -> 'a -> 'a buffer

`create pool bsize h`: Creates a buffer in `pool` with a block size of `bsize`. The block size can be an arbitrary positive integer which is always rounded up to the next multiple of the page size of the operating system. Blocks are the units of allocation of memory.

    val destroy : 'a buffer -> unit

Destroys the buffer
The valid index positions (e.g. for `sub`) are `start` to `start+length-1`:

    val start : 'a buffer -> int

Returns the start index

    val length : 'a buffer -> int

Returns the length

    val contents : 'a buffer -> string

Returns the full contents

    val sub : 'a buffer -> int -> int -> string

Returns a substring

    val blit_to_string : 'a buffer -> int -> string -> int -> int -> unit

Blits contents to a string

    val blit_to_memory : 'a buffer -> int -> Netsys_mem.memory -> int -> int -> unit

Blits contents to a memory buffer

    val access : 'a buffer -> int -> (string -> int -> int -> 'b) -> 'b

`access b pos f`: Gets access to the internal string backing the byte at position `pos`. The function `f` is called as `f s k n` so that `s.[k]` is the requested byte at `pos`. The number `n` is the number of valid bytes in the string.

During the execution of `f` the string `s` is pinned and cannot be deleted by the garbage collector.

    val add_string : 'a buffer -> string -> unit

Adds a string to the end of the buffer

    val add_sub_string : 'a buffer -> string -> int -> int -> unit

Adds a sub string to the end of the buffer

    val add_sub_memory : 'a buffer -> Netsys_mem.memory -> int -> int -> unit

Adds a sub memory buffer to the end of the buffer

    val delete_hd : 'a buffer -> int -> unit

`delete_hd b n`: Deletes `n` bytes from the beginning of the buffer. This means that the `start` index is increased by `n`.

    val clear : 'a buffer -> unit

Deletes all contents of the buffer

    val header : 'a buffer -> 'a

Returns the header

    val descr_of_buffer : 'a buffer -> 'a buffer_descr

Returns the descriptor

    val buffer_of_descr : Netmcore.res_id ->
           'a buffer_descr -> 'a buffer

Look up the buffer for this descriptor

    val heap : 'a buffer -> Obj.t Netmcore_heap.heap

Returns the underlying heap