MQ(4) MQ(4)
NAME
mq - message queue
SYNOPSIS
mq [ -D ] [ -s name ] [ -m mtpt ]
DESCRIPTION
Mq serves a 9p file tree representing groups of buffered
two-way data streams for multiple readers and writers acces-
sible through the standard read(2) and write(2) file I/O
interface.
OVERVIEW
Streams may be organized within an arbitrary file tree
structure, which provides a means of namespacing and group-
ing.
<group>
<group>*
<stream>*
order
ctl
A directory denotes a group of streams. Any number of
streams and sub-groups may be created within a group.
Grouped streams share configuration and an order file.
The read-only meta-stream called order provides ordering
information for data written to streams within a group. Spe-
cial readers, such as mq-cat(1), can tap into this stream to
retrieve data coming from multiple streams in the same order
it was written.
Reading the ctl file yields status and configuration infor-
mation for the group. Group owner can configure the group
by writing control messages to the ctl file. Various sup-
ported stream modes and other properties are explained in
the following sections.
STREAMS
The data mode of the stream group determines the semantics
of data read from the streams.
Message mode (default)
Write boundaries are preserved: each read terminates
when the read buffer is full or after reading the last
byte of a write, whichever comes first. Readers which
read less than the size of the corresponding write get
a partial message, with no way of knowing this hap-
pened. This implies that communicating processes
should agree on the maximum size of messages sent on
the stream. Without specific agreement it is recom-
mended that writes don't exceed 8192 bytes — the size
of the cat(1) read buffer.
Coalesced mode
Coalesce writes into a contiguous byte-stream: each
read terminates when the read buffer is full or after
reading the last byte on the stream.
In both modes, if there's no data to read the read requests
are blocked until new data is written.
Writing to the stream causes the write to be appended to the
stream queue. The write is then immediately distributed to
any blocked stream readers, as well as any blocked order
file readers. Finally the write request is responded to.
Note, however, that a successful write only signals that the
write was fully processed by mq(4). It does not signal that
the data was received on the reader's end nor that it was
processed by readers in any way.
Readers lagging behind, as well as so-called late readers,
will be satisfied from the queue at individual pace.
There are three queue replay modes which determine how the
late readers — those who open a non-empty stream — are han-
dled.
No replay (default)
A late reader is pointed to the very end of the queue,
making it wait for fresh data to arrive.
Replay most recent
A late reader is immediately responded to with the most
recently queued data, if any.
Replay entire queue
The late reader is pointed to the start of stream
queue, letting it receive all the data that was writ-
ten.
The amount of data persisted, the queue depth, is determined
by the replay mode and a configurable depth parameter. For
no-replay and most-recent streams the depth is based on the
readers' progress through the queue: once all readers got
the write it is dropped from the queue as it becomes unac-
cessible. For full-replay streams the depth is determined
by the depth parameter, which is infinite by default but may
be set to a certain number of writes or their combined size
in bytes; the queue may also be cleared manually. As the
queue fills up the old writes are dropped to make place for
new ones. Slow readers who haven't reached the cutoff point
are dropped with an error; this is to prevent resource
exhaustion by faulty or malicious readers.
USAGE
With no flags mq(4) speaks 9p on standard I/O descriptors.
The -s flag posts the 9p channel name to srv(3) instead, and
the -m flag mounts the server at mtpt. The -D flags turns on
the 9p trace on error descriptor.
Creating a directory allocates a new stream group, with the
files ctl and order being created automatically. Similarly,
streams are allocated by creating files inside the group
directory. On startup an empty stream group is allocated at
the root level.
The file order can be read to obtain messages containing
filenames of streams in sequence with writes happening on
the named streams. Each message contains a single filename.
The ctl file accepts commands which change the configuration
of streams within the group, as detailed in the previous
section. Following is a short reference of the supported
commands:
data message | coalesce Sets the data mode.
replay off | last | all Sets the queue replay mode.
depth <size> | <count> Sets the queue depth. The
size argument is specified in
bytes, unless suffixed by K,
M, or G. The count argument
is a number. Depth of 0 means
infinity.
By default only the group owner is allowed to make changes
to the configuration. This is enforced through usual file
permissions. It is, however, not advisable, and certain to
cause trouble, to change the configuration after clients
have connected.
EXAMPLES
See the next section for full example programs.
SEE ALSO
mq-cat(1), pin(1)
SOURCE
git://src.a-b.xyz/mq
BUGS
No filesystem group permission checking is done, yet. This
implies that only a single owner is allowed.
Half of this stuff is not implemented... and sure, the bugs,
bugs — there'll be more, too.