Reference

The following provides detailled documentation about types and methods provided by the InterProcessCommunication package. This information is also available from the REPL by typing ? followed by the name of a method or a type.

Semaphores

# InterProcessCommunication.Semaphore — Type

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.

# InterProcessCommunication.post — Method

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.

# Base.wait — Method

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.

# Base.timedwait — Method

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.

# InterProcessCommunication.trywait — Method

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.

Shared Memory

# InterProcessCommunication.SharedMemory — Type

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

yields 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 can be used to specify which access permissions are granted. By default, only reading and writing by the user is granted.

Keyword volatile can be used 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. By default, the shared memory is destroyed when no longer in use.

To retrieve an existing shared memory object, call:

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.

Some methods are extended for shared memory objects. Assuming shm is an instance of SharedMemory, then:

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

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

rm(shm)

Signals

# InterProcessCommunication.SigSet — Type

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]

# InterProcessCommunication.SigAction — Type

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!.

# InterProcessCommunication.SigInfo — Type

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.

# InterProcessCommunication.sigaction — Function

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.

Wrapped arrays

# InterProcessCommunication.WrappedArray — Type

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.

Utilities

# InterProcessCommunication.TimeSpec — Type

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.

# InterProcessCommunication.TimeVal — Type

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.

# InterProcessCommunication.clock_getres — Function

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).

# InterProcessCommunication.clock_gettime — Function

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.

# InterProcessCommunication.clock_settime — Function

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).

# InterProcessCommunication.gettimeofday — Function

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).

# InterProcessCommunication.nanosleep — Function

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.

# InterProcessCommunication.umask — Function

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.

Exceptions

# InterProcessCommunication.TimeoutError — Type

TimeoutError is used to throw a timeout exception.