Go to the first, previous, next, last section, table of contents.


Function: ]signal { [event] -> }
file: 01-C-event.t
package: muf
status: alpha

This function is the most vanilla way to invoke the event system.

The argument block to this function consists of keyVal pairs, and will be handed unchanged to the signal handlers. (The block may currently not contain more than 64 keyval pairs: See the rationale at end of this subsection.)

One keyval pair must always be present:

:event C

where C is a Event object. This specifies the particular type of event being signaled.

An important optional keyval pair is

:job J

where J is a Job object. If this keyval is provided, the signal is sent to the specified job, and is handled (or not) by whatever handlers that job has established. If no :job J keyval is provided, the signal is sent to the currently executing job.

In order to send a signal to another job, the actingUser must be the same as the actualUser of the other job, or else must be root running with the OMNIPOTENT bit set: Otherwise the signal will be silently ignored.

Any other keyval pairs present will be ignored by ]signal but may be meaningful to any signal handlers invoked.

Signals sent to other jobs via ]signal always return.

Signals sent to the currently running job return if and only if all "relevant" handlers return.

A handler is "relevant" if the event associated with the handler is the same as the event C being signaled (or is a parent of C), and if that handler is not part of a handler set already handling a signal.

Note that these signals are unreliable: There is no guarantee that any handler will be invoked, even if present, since it might be busy handling another signal.

Rationale: The definition of this function was selected with the intention that it be a primary means of communication between Muq jobs, yet anticipating that in general these jobs may not be on the same Muq server. It is intended that one reasonable implementation of signals in such a case be via UDP packet.

Unreliable signals are appropriate for a variety of state-update tasks in multi-user interactive settings, such as tracking cursor position: If a particular update gets lost, the next update will rectify matters anyhow, so there is no need for expensive reliable-delivery mechanisms, and in particular no need to block the sender for a full roundTrip time over the network.

It is anticipated that when reliable delivery of information is needed, that streams rather than signals will be used, and that the underlying implementation will in this case use a reliable stream protocol such as tcp.

When appropriate, you may of course implement your own acknowledgement protocol on top of the basic Muq signal facility: Waiting for a return signal after each signal, or checking for a heartbeat every N milliseconds or whatever.

Signal blocks are limited to 128 entries (configurable by changing JOB_SIGNAL_BLOCK_MAX and recompiling) partly because signals are intended for brief notifications, not (say) file transfer, and need to fit in a datagram without excessive fragmentation or spamming the net interface.

Future directions: Due to limitations such as UDP packet size, it is likely that future Muq releases will place a limit on the total size in bytes of the keyword names. It is reasonably safe to assume that such limit will support an aggregate half a K or so of keyval names. (The default Maximum Transmission Unit size on the Internet is 576 bytes; Ideally ]signal blocks should be about this size, or smaller.)

See section ]doSignal.

Go to the first, previous, next, last section, table of contents.