.TH MPIPEFS 4 .SH NAMEmpipefs, mp-writer \- one-way many to many communication.SH SYNOPSIS.B mpipefs[.B -D][.B -s.I service][.I mnt] .B mount.I /srv/service.I dir[.I spec] spec = '[.I -e num-slots][.I -b][.I name]' .B mp-writer[.B -D][.B -n.I num-times][.B -s.I message-size][.B -e.I num-enum-slots][.B -i.I stream-from-path][.B -o.I stream-to-path].I pipe-path .SH DESCRIPTION.PPAn.IR attach (5)of this device allocates a new  I/O stream whose namecan be specified as part of the .I specarguments.  .B NOTE: the name must always be specified as the last argumentof the mount spec..PPFor normal read and write operations, behavior isidentical to the.IR pipe(3) , except that the multipipes are unidirectional and only a single file is provided per attach. Attempting to open the pipe.I ORDWRwill fail, writers must open with.I OWRITEand readers must open with.I OREAD.Also, there isn't any implicit buffering in the mpipe, so writerswill block until a reader becomes available and vice versa.Similar to .IR pipe(3) ,when all writers of a pipe close, it is marked as hungup, and readersreceive an EOF.  When all readers and writers close, the pipe is resetand may be re-used.  When the pipe is reset, any special flags (broadcasts,enumerations) will persist..PPThe name of the file being provided by the device canbe specified as an attach parameter using the mount.I spec.If no name is given, it will default to .I data..PPThe mpipe can also be created as a broadcast pipe, by providingthe -b option as part of the .I spec.When a broadcast pipe is used, all readers will receive a copy of whatwas written.  A failure on any reader will trigger the write to fail.  At themoment, a partial read is treated as a failure.  Also, while in broadcastmost, a write with no readers will deposit data in the bit bucket..SS Header Control Blocks.PPIn additon to normal reads and writes, writers may inject header controlblocks into the pipe which can either act as control messages or describe thedata following the header.  Header control blocks are marked by being at offset.I (ulong)~0 and follow a similar convention to plumbing messages in that they usenewline separated fields as arguments.  The fields, in order, are:.RS.TF ndata.TP.B typeheader type (single byte).TP.B sizesize of message (in bytes).TP.B whichdestination pipe enumeration (numeric).TP.B pathdestination for splice command (full filesystem path).RE Not all fields are used by all header types..PD.PPAt the moment three types of header packets are supported:.RS.TF ndata.TP.B 'p'specifies a packet which can be used for long messages or enumerated pipes..TP.B '>'specifies a splice-to control block.TP.B '<'specifies a splice-from control block.RE.PD.SS Long Messages.PPLong messages, those intended for a single reader but with a sizegreater than the atomic I/O capable from the pipe can be accomodatedby using a header control block with the size field specifying the total size ofthe message.  The writer will be linked to a particular reader until thatmany bytes have been sent as data messages..SS Enumerated Pipes.PPEnumerated pipes allow the writer to specify a designated reader for any particular message (including long messages as mentioned above).The only effective way to use enumerated pipes is to specify the numberof reader enumerations as part of the initial mount.I specfor the pipe, using the -e .I specargument.  This will create the specified number of slots for enumerationsas part of the pipes.  New readers will be assigned round-robin to these slotsas they open the pipe.  An attempt to backfill readers to underpopulated slotsis made in order to balance the readers among the available slots and allownew readers to fill in gaps left by old readers..PPIf a reader for a particular enumeration is not yet available, the writer will block..SS Splicing.PPSplicing can be used to link mpipes together or to tether mpipes to normal pipesor even to normal files.  The .B splice-tocontrol block will start a thread which will act as a reader write anything itreads to to the target path specified in the header control block.The .B splice-fromcontrol block will start a thread which will act as a writer, reading newdata from the target path specified in the header control block.Either thread will exit on receiving EOF or an error from their target.Niether currently makes use of the .I sizeor .I whichfield in the header control block..SS mp-writer.PP.B mp-writeris a test application which can be used to test writing different typesof control blocks to the pipe. Using the .I -Dflag will make things very chatty so you can see what's going onfrom a protocol perspective.  The.I -nflags will specify the total number of messages to sendwhile the.I -sflag allows you to specify the size of messages (to test large packets).The.I -iand .I -olet you specify splice-in and splice-out instructions.  They aremutually exclusive with the other options. .SH BUGS.PPThe broadcast mode probably needs to be made more consistentwith respect to the behavior of the other modes and be integreatedwith splicing..PPAlso, flushing outstanding requests against the mpipe is currentlynot supported and probably should be. .SH "SEE ALSO".IR pipe (2).IR push (1).IR execfs (4).IR taskfs (4).SH SOURCE.B /sys/src/cmd/mpipefs.c.nf.B /sys/src/cmd/mp-writer.c