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.