shithub: mq

--- a/README.md

+++ b/README.md

@@ -1,80 +1,44 @@

 mq(4) — message queue

 ====

-`Mq` serves a file tree representing buffered two-way data streams

-for multiple readers and writers with selectable reading and

-writing semantics.

+Mq serves a 9p file tree representing groups of buffered two-way data

+streams for multiple readers and writers accessible through the

+standard read(2) and write(2) file I/O interface.

-Structure

+Overview

 ----

-Streams may be created and organized within an arbitrary file tree

-structure, providing an obvious way of namespacing and grouping.

+Streams may be organized within an arbitrary file tree structure, which

+provides a means of namespacing and grouping.

-A directory denotes a group of streams.  Grouped streams share the same

-configuration and may be related by time-based ordering of data

-written to them.  The ordering information is provided by a meta-stream

-called 'order' that readers, such as `mq-cat(1)`, may use to retrieve data

-in a reliable order.

+	<group>

+		<group>*

+		<stream>*

+		order

+		ctl

-Stream semantics

-----

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

-Many aspects of stream behaviour may be chosen at group creation

-time to suit different kinds of applications.

+The read-only meta-stream called order provides ordering information for

+data written to streams within a group.  Special 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

-    * message mode; preserve message boundaries (default)

-    * stream mode; coalesce messages (not implemented)

-    * (?) static mode; file-like, seekable, eof (not implemented)

-* Writing

-    * non-blocking

-    * blocking; wait one reader, wait all readers (not implemented)

-* History replay

-    * no replay (default)

-    * most recent (not implemented)

-    * entire history

-* Queue persistence

-    * in-memory (default)

-    * (?) on disk (not implemented)

+See the `mq(4)` manual page for complete description of supported

+data modes, queue replay options, usage reference, and other details.

-Caveats

-----

-Boundary preservation in message mode only works if none of the

-writes exceed the size of the shortest reader. A short reader will receive

-the message in two or more parts. There is no way for such a reader

-to know that it received split data. This means that readers and writers

-must somehow agree on the maximum size of messages that will

-be sent on the stream. Without specific agreement the writes should

-not exceed 8192 bytes -- the `cat(1)` program buffer size.

-Note: current implementation does not split the read response, it just

-advances to the next message. This will be fixed.

-Access control

-----

-Access control is provided through filesystem permissions.  By default

-only the owner may create and remove groups and streams, as well as

-change their configuration.

-Authentication, if needed, may be done externally, for example by

-wrapping the `mq(4)` channel with `tlssrv(8)`.

-Note: current implementation does not check group membership.

-This will be fixed.

 Examples

 ----

-Mount the `mq(4)` file server and use it to create a detached `rc(1)`

-shell that can be attached to from multiple places.

+Mount the `mq(4)` file server and use it to persist an `rc(1)` shell session.

 	mq -s detach

 	mount -c /srv/detach /n/detach

 	mkdir /n/detach/rc

 	cd /n/detach/rc

-	echo replay on >ctl

+	echo replay all >ctl

 	touch fd0 fd1 fd2

 	rc -i <fd0 >>fd1 >>[2]fd2 &

@@ -82,6 +46,8 @@

 	cat fd1 & cat fd2 & cat >>fd0

-The included program `attach(1)` provides a more polished interface for

-detaching programs, it also makes use of the data ordering information

-to faithfully reproduce session history.

+The program `pin(1)` provides a polished interface for persisting

+program sessions.  It also makes use of the data ordering feature for

+faithful reproduction of session history.

+The program `mq-cat(1)` is an example of an ordered multi-stream reader.