module Netmcore_sem

: sig


Semaphores are here defined as values that reside in shared heaps ([root:Netmcore_heap]), for example in the header field of [root:Netmcore_array] or somewhere else in heap-allocated data structures.

In order to ensure that the semaphore is in the heap, the special function create must be used to initialize it there. As create requires a mutator as argument, this is only possible by calling create from the callback of Netmcore_heap.modify.

Semaphores are special values, and cannot be copied or moved.

Note that [root:Netsys_posix] provides wrappers for direct use of the semaphore functionality of the OS. These wrappers, however, cannot be used together with heaps, because semaphores are there represented as bigarrays, which cannot be pushed to heaps. This module here uses a trick to make it possible nevertheless.

type semaphore
val dummy : unit -> semaphore

A dummy semaphore is non-functional, but can be used to put something into semaphore-typed variables

val create : Netmcore_heap.mutator -> int -> semaphore

create m value: Creates a semaphore with initial value, and pushes it to the heap, using the mutator m.

After being pushed to the heap, the semaphore can be used. It is nonsense to copy it outside the heap.

val destroy : semaphore -> unit

Destroys the semaphore

val getvalue : semaphore -> int

Returns the value of the semaphore

val post : semaphore -> unit

Increments the semaphore by one, and notifies one of the waiting processes.

val wait : semaphore -> Netsys_posix.sem_wait_behavior -> unit

Decrements the semaphore by one. Semaphores cannot become negative. If the semaphore is already 0, the wait behavior defines how to go on:

Waiting is restarted after running a signal handler.