Reference

Named Semaphores

Semaphore(name, value; perms=0o600, volatile=true) -> sem

creates a new named semaphore identified by the string name of the form "/somename" and initial value set to value. An instance of Semaphore{String} is returned. Keyword perms can be used to specify access permissions. Keyword volatile specifies whether the semaphore should be unlinked when the returned object is finalized.

Semaphore(name) -> sem

opens an existing named semaphore and returns an instance of Semaphore{String}.

To unlink (remove) a persistent named semaphore, simply do:

rm(Semaphore, name)

If the semaphore does not exists, the error is ignored. A SystemError is however thrown for other errors.

For maximum flexibility, an instance of a named semaphore may also be created by:

open(Semaphore, name, flags, mode, value, volatile) -> sem

where flags may have the bits IPC.O_CREAT and IPC.O_EXCL set, mode specifies the granted access permissions, value is the initial semaphore value and volatile is a boolean indicating whether the semaphore should be unlinked when the returned object sem is finalized. The values of mode and value are ignored if an existing named semaphore is open. The permissions settings in mode are masked against the process umask.

Anonymous Semaphores

Anonymous semaphores are backed by memory objects providing the necessary storage.

Semaphore(mem, value; offset=0, volatile=true) -> sem

initializes an anonymous semaphore backed by memory object mem with initial value set to value and returns an instance of Semaphore{typeof(mem)}. Keyword offset can be used to specify the address (in bytes) of the semaphore data relative to pointer(mem). Keyword volatile specify whether the semaphore should be destroyed when the returned object is finalized.

Semaphore(mem; offset=0) -> sem

yields an an instance of Semaphore{typeof(mem)} associated with an initialized anonymous semaphore and backed by memory object mem at relative position (in bytes) specified by keyword offset.

The number of bytes needed to store an anonymous semaphore is given by sizeof(Semaphore) and anonymous semaphore must be aligned in memory at multiples of the word size (that is Sys.WORD_SIZE >> 3 in bytes). Memory objects used to store an anonymous semaphore must implement two methods: pointer(mem) and sizeof(mem) to yield respectively the base address and the size (in bytes) of the associated memory.

See also: post, wait, timedwait, trywait.

post(sem)

increments (unlocks) the semaphore sem. If the semaphore's value consequently becomes greater than zero, then another process or thread blocked in a wait call on this semaphore will be woken up.

See also: Semaphore, wait, timedwait, trywait.

wait(sem)

decrements (locks) the semaphore sem. If the semaphore's value is greater than zero, then the decrement proceeds and the function returns immediately. If the semaphore currently has the value zero, then the call blocks until either it becomes possible to perform the decrement (i.e., the semaphore value rises above zero), or a signal handler interrupts the call (in which case an instance of InterruptException is thrown). A SystemError may be thrown if an unexpected error occurs.

See also: Semaphore, post, timedwait, trywait.

timedwait(sem, secs)

decrements (locks) the semaphore sem. If the semaphore's value is greater than zero, then the decrement proceeds and the function returns immediately. If the semaphore currently has the value zero, then the call blocks until either it becomes possible to perform the decrement (i.e., the semaphore value rises above zero), or the limit of secs seconds expires (in which case an instance of TimeoutError is thrown), or a signal handler interrupts the call (in which case an instance of InterruptException is thrown).

See also: Semaphore, post, wait, trywait.

trywait(sem) -> boolean

attempts to immediately decrement (lock) the semaphore sem returning true if successful. If the decrement cannot be immediately performed, then the call returns false. If an interruption is received or if an unexpected error occurs, an exception is thrown (InterruptException or SystemError repectively).

See also: Semaphore, post, wait, timedwait.

shm = SharedMemory(id, len; perms=0o600, volatile=true)

creates a new shared memory object identified by id and whose size is len bytes. The identifier id can be a string starting by a '/' to create a POSIX shared memory object or a System V IPC key to create a System V shared memory segment. In this latter case, the key can be IPC.PRIVATE to automatically create a non-existing shared memory segment.

Keyword perms is to specify the access permissions to be granted. By default, only reading and writing by the user are granted.

Keyword volatile is to specify whether the shared memory is volatile or not. If non-volatile, the shared memory will remain accessible until explicit destruction or system reboot. If volatile (the default), the shared memory is automatically destroyed when no longer in use by any processes.

To retrieve an existing shared memory object, call:

shm = SharedMemory(id; readonly=false)

where id is the shared memory identifier (a string, an IPC key, or a System V IPC identifier of shared memory segment as returned by ShmId). Keyword readonly can be set true if only read access is needed. Note that method shmid(obj) may be called to retrieve the identifier of the shared memory object obj.

A number of accessors are available for a shared memory objects shm:

pointer(shm)    # base address of the shared memory
sizeof(shm)     # number of bytes of the shared memory
shmid(shm)      # identifier of the shared memory

To ensure that shared memory object shm is eventually destroyed, call:

rm(shm)

See also ShmId, shmid, and shmrm.

id = ShmId(id)
id = ShmId(shm)
id = ShmId(arr)
id = ShmId(key; readlony=false)

yield the the identifier of the existing System V shared memory segment associated with the value of the first argument: id is the identifier of the shared memory segment, shm is a System V shared memory object, arr is an array attached to a System V shared memory segment, and key is the key associated with the shared memory segment. In that latter case, keyword readlony can be set true to request read-only access; otherwise read-write access is requested.

See also: shmid, shmget.

ShmInfo

is the type of the structure storing information about a System V shared memory segment. The call ShmInfo(arg) is equivalent to shminfo(arg).

id = shmid(arg)

yields the identifier of an existing POSIX shared memory object or System V shared memory segment identifed by arg or associated with arg. Argument can be:

• An instance of SharedMemory.

• An instance of WrappedArray whose contents is stored into shared memory.

• A string starting with a '/' (and no other '/') to identify a POSIX shared memory object.

• An instance of IPC.Key to specify a System V IPC key associated with a shared memory segment. In that case, an optional second argument readonly can be set true to only request read-only access; otherwise read-write access is requested.

• An instance of ShmId to specify a System V shared memory segment.

See also: SharedMemory, shmrm.

id = shmget(key, siz, flg)

yields the identifier of the System V shared memory segment associated with the System V IPC key key. A new shared memory segment with size siz (in bytes, possibly rounded up to a multiple of the memory page size IPC.PAGE_SIZE) is created if key has the value IPC.PRIVATE or if bit IPC_CREAT is set in flg and no shared memory segment corresponding to key exists.

Argument flg is a bitwise combination of flags. The least significant 9 bits specify the permissions granted to the owner, group, and others. These bits have the same format, and the same meaning, as the mode argument of chmod. Bit IPC_CREAT can be set to create a new segment. If this flag is not used, then shmget will find the segment associated with key and check to see if the user has permission to access the segment. Bit IPC_EXCL can be set in addition to IPC_CREAT to ensure that this call creates the segment. If IPC_EXCL and IPC_CREAT are both set, the call will fail if the segment already exists.

ptr = shmat(id, readonly)

attaches a System V shared memory segment to the address space of the caller. Argument id is the identifier of the shared memory segment. Boolean argument readonly specifies whether to attach the segment for read-only access; otherwise, the segment is attached for read and write accesses and the process must have read and write permissions for the segment. The returned value is the address of the shared memory segment for the caller.

See also: shmdt, shmrm.

shmdt(ptr)

detaches a System V shared memory segment from the address space of the caller. Argument ptr is the pointer returned by a previous shmat call.

See also: shmat, shmget.

shmrm(arg)

removes the shared memory associated with arg. If arg is a name, the corresponding POSIX named shared memory is unlinked. If arg is a key or identifier of a BSD shared memory segment, the segment is marked to be eventually destroyed. Argument arg can also be a SharedMemory object.

The rm method may also be called to remove an existing shared memory segment or object. There are several possibilities:

rm(SharedMemory, name)  # `name` identifies a POSIX shared memory object
rm(SharedMemory, key)   # `key` is associated with a BSD shared memory segment
rm(id)                  # `id` is the identifier of a BSD shared memory segment
rm(shm)                 # `shm` is an instance of `SharedMemory`

See also: SharedMemory, shmid, shmat.

shmctl(id, cmd, buf)

performs the control operation specified by cmd on the System V shared memory segment whose identifier is given in id. The buf argument is a byte array large enough to store a shmid_ds C structure.

See also shminfo, shmcfg and shmrm.

id = shmcfg(arg, perms) -> id

changes the access permissions of a System V IPC shared memory segment identified by arg, a System V IPC shared memory identifier, a shared array attached to a System V IPC shared memory segment, or a System V IPC key associated with a shared memory segment. Argument perms specifies bitwise flags with the new permissions. The identifier of the shared memory segment is returned.

See also ShmId, shmget, shmctl and SharedMemory.

info = shminfo(arg)

yields information about the System V shared memory segment identified or associated with arg, the identifier of the shared memory segment, a shared array attached to the shared memory segment, or the System V IPC key associated with the shared memory segment.

See also ShmInfo, ShmId, shmget, shmat, and SharedMemory.

info = shminfo!(arg, info)

overwrites info (an instance of ShmInfo) with the information about the System V shared memory segment identified by or associated with arg. See shminfo for more details.

SigSet represents a C sigset_t structure. It should be considered as opaque, its contents is stored as a tuple of unsigned integers whose size matches that of sigset_t.

Typical usage is:

sigset = SigSet()
sigset[signum] -> boolean
sigset[signum] = boolean
fill!(sigset, boolean) -> sigset

where signum is the signal number, an integer greater or equal 1 and less or equalIPC.SIGRTMAX. Real-time signals have a number signum such that IPC.SIGRTMIN ≤ signum ≤ IPC.SIGRTMAX

Non-exported methods:

IPC.sigfillset!(sigset)          # same as fill!(signum, true)
IPC.sigemptyset!(sigset)         # same as fill!(signum, false)
IPC.sigaddset!(sigset, signum)   # same as sigset[signum] = true
IPC.sigdelset!(sigset, signum)   # same as sigset[signum] = false
IPC.sigismember(sigset, signum)  # same as sigset[signum]

SigAction is the counterpart of the C struct sigaction structure. It is used to specify the action taken by a process on receipt of a signal. Assuming sa is an instance of SigAction, its fields are:

sa.handler         # address of a signal handler
sa.mask            # mask of the signals to block
sa.flags           # bitwise flags

where sa.handler is the address of a C function (can be SIG_IGN or SIG_DFL) to be called on receipt of the signal. This function may be given by cfunction. If IPC.SA_INFO is not set in sa.flags, then the signature of the handler is:

function handler(signum::Cint)::Nothing

that is a function which takes a single argument of type Cint and returns nothing; if IPC.SA_INFO is not set in sa.flags, then the signature of the handler is:

function handler(signum::Cint, siginf::Ptr{SigInfo}, unused::Ptr{Cvoid})::Nothing

that is a function which takes 3 arguments of type Cint, Ptr{SigInfo}, Ptr{Cvoid} repectively and which returns nothing. See SigInfo for a description of the siginf argument by the handler.

Call:

sa = SigAction()

to create a new empty structure or

sa = SigAction(handler, mask, flags)

to provide all fields.

See also SigInfo, sigaction and sigaction!.

SigInfo represents a C siginfo_t structure. It should be considered as opaque, its contents is stored as a tuple of unsigned integers whose size matches that of siginfo_t but, in principle, only a pointer of it should be received by a signal handler established with the SA_SIGINFO flag.

Given ptr, an instance of Ptr{SigInfo} received by a signal handler, the members of the corresponding C siginfo_t structure are retrieved by:

IPC.siginfo_signo(ptr)  # Signal number.
IPC.siginfo_code(ptr)   # Signal code.
IPC.siginfo_errno(ptr)  # If non-zero, an errno value associated with this
                        # signal.
IPC.siginfo_pid(ptr)    # Sending process ID.
IPC.siginfo_uid(ptr)    # Real user ID of sending process.
IPC.siginfo_addr(ptr)   # Address of faulting instruction.
IPC.siginfo_status(ptr) # Exit value or signal.
IPC.siginfo_band(ptr)   # Band event for SIGPOLL.
IPC.siginfo_value(ptr)  # Signal value.

These methods are unsafe because they directly use an address. They are therefore not exported by default. Depending on the context, not all members of siginfo_t are relevant (furthermore they may be defined as union and thus overlap in memory). For now, only the members defined by the POSIX standard are accessible. Finally, the value given by IPC.siginfo_value(ptr) represents a C type union sigval (an union of a C int and a C void*), in Julia it is returned (and set in sigqueue) as an integer large enough to represent both kind of values.

sigaction(signum) -> sigact

yields the current action (an instance of SigAction) taken by the process on receipt of the signal signum.

sigaction(signum, sigact)

installs sigact (an instance of SigAction) to be the action taken by the process on receipt of the signal signum.

Note that signum cannot be SIGKILL nor SIGSTOP.

See also SigAction and sigaction!.

sigaction!(signum, sigact, oldact) -> oldact

installs sigact to be the action taken by the process on receipt of the signal signum, overwrites oldact with the previous action and returns it. Arguments sigact and oldact are instances of SigAction.

See SigAction and sigaction for more details.

sigpending() -> mask

yields the set of signals that are pending for delivery to the calling thread (i.e., the signals which have been raised while blocked). The returned value is an instance of SigSet.

See also: sigpending!.

sigpending!(mask) -> mask

overwites mask with the set of pending signals and returns its argument.

See also: sigpending.

sigprocmask() -> cur

yields the current set of blocked signals. To change the set of blocked signals, call:

sigprocmask(how, set)

with set a SigSet mask and how a parameter which specifies how to interpret set:

• IPC.SIG_BLOCK: The set of blocked signals is the union of the current set and the set argument.

• IPC.SIG_UNBLOCK: The signals in set are removed from the current set of blocked signals. It is permissible to attempt to unblock a signal which is not blocked.

• IPC.SIG_SETMASK: The set of blocked signals is set to the argument set.

See also: sigprocmask!.

sigprocmask!(cur) -> cur

overwrites cur, an instance of SigSet, with the current set of blocked signals and returns it. To change the set of blocked signals, call:

sigprocmask!(how, set, old) -> old

which changes the set of blocked signals according to how and set (see sigprocmask), overwrites old, an instance of SigSet, with the previous set of blocked signals and returns old.

See also: sigprocmask.

sigqueue(pid, sig, val=0)

sends the signal sig to the process whose identifier is pid. Argument val is an optional value to join to to the signal. This value represents a C type union sigval (an union of a C int and a C void*), in Julia it is specified as an integer large enough to represent both kind of values.

sigsuspend(mask)

temporarily replaces the signal mask of the calling process with the mask given by mask and then suspends the process until delivery of a signal whose action is to invoke a signal handler or to terminate a process.

If the signal terminates the process, then sigsuspend does not return. If the signal is caught, then sigsuspend returns after the signal handler returns, and the signal mask is restored to the state before the call to sigsuspend.

It is not possible to block IPC.SIGKILL or IPC.SIGSTOP; specifying these signals in mask, has no effect on the process's signal mask.

sigwait(mask, timeout=Inf) -> signum

suspends execution of the calling thread until one of the signals specified in the signal set mask becomes pending. The function accepts the signal (removes it from the pending list of signals), and returns the signal number signum.

Optional argument timeout can be specified to set a limit on the time to wait for one the signals to become pending. timeout can be a real number to specify a number of seconds or an instance of TimeSpec. If timeout is Inf (the default), it is assumed that there is no limit on the time to wait. If timeout is a number of seconds smaller or equal zero or if timeout is TimeSpec(0,0), the methods performs a poll and returns immediately. It none of the signals specified in the signal set mask becomes pending during the allowed waiting time, a TimeoutError exception is thrown.

See also: sigwait!, TimeSpec, TimeoutError.

sigwait!(mask, info, timeout=Inf) -> signum

behaves like sigwait but additional argument info is an instance of SigInfo to store the information about the accepted signal, other arguments are as for the sigwait method.

WrappedArray(mem, [T [, dims...]]; offset=0)

yields a Julia array whose elements are stored in the "memory" object mem. Argument T is the data type of the elements of the returned array and argument(s) dims specify the dimensions of the array. If dims is omitted the result is a vector of maximal length (accounting for the offset and the size of the mem object). If T is omitted, UInt8 is assumed.

Keyword offset may be used to specify the address (in bytes) relative to pointer(mem) where is stored the first element of the array.

The size of the memory provided by mem must be sufficient to store all elements (accounting for the offset) and the alignment of the elements in memory must be a multiple of Base.datatype_alignment(T).

Another possibility is:

WrappedArray(mem, dec)

where mem is the "memory" object and dec is a function in charge of decoding the array type and layout given the memory object. The decoder is applied to the memory object as follow:

dec(mem) -> T, dims, offset

which must yield the data type T of the array elements, the dimensions dims of the array and the offset of the first element relative to pointer(mem).

Restrictions

The mem object must extend the methods pointer(mem) and sizeof(mem) which must respectively yield the base address of the memory provided by mem and the number of available bytes. Furthermore, this memory is assumed to be available at least until object mem is reclaimed by the garbage collector.

Shared Memory Arrays

WrappedArray(id, T, dims; perms=0o600, volatile=true)

creates a new wrapped array whose elements (and a header) are stored in shared memory identified by id (see SharedMemory for a description of id and for keywords). To retrieve this array in another process, just do:

WrappedArray(id; readonly=false)

See Also

SharedMemory.

TimeSpec(sec, nsec)

yields an instance of TimeSpec for an integer number of seconds sec and an integer number of nanoseconds nsec since the Epoch.

TimeSpec(sec)

yields an instance of TimeSpec for a, possibly fractional, number of seconds sec since the Epoch. Argument can also be an instance of TimeVal.

Call now(TimeSpec) to get the current time as an instance of TimeSpec.

Addition and subtraction involving and instance of TimeSpec yield a TimeSpec result. For instance:

now(TimeSpec) + 3.4

yields a TimeSpec instance with the current time plus 3.4 seconds.

typemin(TimeSpec)
typemax(TimeSpec)

respectively yield the minimum and maximum normalized time values for an instance of TimeSpec.

TimeVal(sec, usec)

yields an instance of TimeVal for an integer number of seconds sec and an integer number of microseconds usec since the Epoch.

TimeVal(sec)

yields an instance of TimeVal with a, possibly fractional, number of seconds sec since the Epoch. Argument can also be an instance of TimeSpec.

Call now(TimeVal) to get the current time as an instance of TimeVal.

Addition and subtraction involving and instance of TimeVal yield a TimeVal result. For instance:

now(TimeVal) + 3.4

yields a TimeVal instance with the current time plus 3.4 seconds.

typemin(TimeVal)
typemax(TimeVal)

respectively yield the minimum and maximum normalized time values for an instance of TimeVal.

clock_getres(id) -> ts

yields the resolution (precision) of the specified clock id. The result is an instance of IPC.TimeSpec. Clock identifier id can be CLOCK_REALTIME or CLOCK_MONOTONIC (described in clock_gettime).

See also clock_gettime, clock_settime, gettimeofday, nanosleep, IPC.TimeSpec and IPC.TimeVal.

clock_gettime(id) -> ts

yields the time of the specified clock id. The result is an instance of IPC.TimeSpec. Clock identifier id can be one of:

• CLOCK_REALTIME: System-wide clock that measures real (i.e., wall-clock) time. This clock is affected by discontinuous jumps in the system time (e.g., if the system administrator manually changes the clock), and by the incremental adjustments performed by adjtime and NTP.

• CLOCK_MONOTONIC: Clock that cannot be set and represents monotonic time since some unspecified starting point. This clock is not affected by discontinuous jumps in the system time.

See also clock_getres, clock_settime, gettimeofday, nanosleep, IPC.TimeSpec and IPC.TimeVal.

clock_settime(id, ts)

set the time of the specified clock id to ts. Argument ts can be an instance of IPC.TimeSpec or a number of seconds. Clock identifier id can be CLOCK_REALTIME or CLOCK_MONOTONIC (described in clock_gettime).

See also clock_getres, clock_gettime, gettimeofday, nanosleep, IPC.TimeSpec and IPC.TimeVal.

gettimeofday() -> tv

yields the current time as an instance of IPC.TimeVal. The result can be converted into a fractional number of seconds by calling float(tv).

See also: IPC.TimeVal, nanosleep, clock_gettime.

nanosleep(t) -> rem

sleeps for t seconds with nanosecond precision and returns the remaining time (in case of interrupts) as an instance of IPC.TimeSpec. Argument can be a (fractional) number of seconds or an instance of IPC.TimeSpec or IPC.TimeVal.

The sleep method provided by Julia has only millisecond precision.

See also gettimeofday, IPC.TimeSpec and IPC.TimeVal.

umask(msk) -> old

sets the calling process's file mode creation mask (umask) to msk & 0o0777 (i.e., only the file permission bits of mask are used), and returns the previous value of the mask.

See also IPC.maskmode.

IPC.maskmode(mode)

returns the IPC.MASKMODE bits of mode converted to mode_t C type.

Constant IPC.MASKMODE = 0o777 is a bit mask for the granted access permissions (in general it has its 9 least significant bits set).

See also umask.

TimeoutError is used to throw a timeout exception.