Pieces... A "piece" indicates an area of the jukebox to be read or written. Pieces are queued and serviced in FIFO order for each voice stream. A flush operation throws away all of the pieces pending for the stream.

Buffering... Buffers are used to keep track of one chirp and the space it occupies in virtual memory; each buffer has an indication of whether it is destined to or from the jukebox. A voice stream has three queues of buffers: the server buffers are those that are waiting to be processed by the server, the client buffers are those waiting to be processed by the client (ReceiveProc and SendProc), and the idle buffers are those that aren't currently in use. The Open operation allocates a number of buffers and places them on the idle queue; Close frees all of the buffers.

Synchronization... A single monitor lock is used to control access to voice stream handles. Several condition variables are used to control the synchronization among the processes. The server waits on "serverCondition" whenever it is completely out of work; this condition is notified whenever a new stream is opened, a new piece is added to a stream, a buffer is handed to the server, or a stream is being closed (to prod the server to broadcast "closeCondition"). The server broadcasts the "client" condition when it adds a buffer to the client queue, an error occurs, (or it wants work?); this condition is also broadcast when a stream is closed or flushed; a client waits on this condition when it needs a buffer or when it is waiting for the server to write a buffer to disk(?). The "waitCondition" is broadcast whenever a stream becomes empty, flushed, or closed; the WaitEmpty operation waits on this condition. The "closeCondition" is broadcast whenever the server has no work to do (for any stream!); the Close operation waits on this condition.

Error handling... Each voice stream handle contains an errorRope; if this isn't NIL, then an error has occurred for the voice stream, as described by errorRope and errorCode. The server simply sets these fields of the stream handle when it discovers an error. The client processes check for errors and quietly go away if any are discovered. The AddPiece, Check, and Close operations report an error if necessary; errors are also reported whenever a client attempts to get/put data from/to a stream.

Event reporting... A NotifyProc is called when a voice stream begins ($started) or ends ($finished) the playback/recording of a piece, or when it is flushed ($flushed).

The server is responsible for processing pieces by generating chirp-sized buffers to be read or written by the client processes. Thus, the server processes each piece a chirp at a time; the start and length of the piece's interval are adjusted along the way so that they always refer to the portion left to be processed. An important invariant maintained by the server: any buffers waiting to be processed. i.e. that are not on the idle queue, belong to a single piece; the server does not start buffering the next piece until the buffers for the previous piece are completely read or written.

The server operates in an infinite loop that takes the first buffer off the server queue and temporarily places it at the head of the idle queue (GetServerBuffer); if the server queue is empty then the buffer already at the head of the idle queue will be used. The server then jumps out of the monitor and safely processes the buffer while is sits on the idle queue.

The server first writes out the chirp in the buffer if it needs to be written. The server then tries to continue working on the current piece. If the current piece has been completely processed, then the server continues writing any buffers associated with it (by short-circuiting the rest of its loop); when the piece and all of its buffers have been processed, the server moves on to the next piece.

Next, the next chirp of the piece is read into the buffer if the piece is for playback or a partial chirp is being recorded (note that recorded intervals can start in the middle of a chirp but cannot end in the middle of a chirp!). If the piece's interval does not include the first part of the chirp just read, then the server uses the run data to determine where in the buffer the desired interval actually starts (recall that silence is not explicitly stored in a chirp so computing intervals is tricky). The server does not spend time analyzing the run data to find the end of an interval (so the buffer's block may be longer than needed but who cares).

When done, the server transfers the buffer from the idle queue to the client queue (GiveClientBuffer). The server then starts the loop again, i.e. it tries to get another buffer from the server queue.

In VoiceStreamSocketImpl.mesa: This process sets up a connection with an Etherphone, then receives incoming packets from the Etherphone. It reads packets continuously until either the voice stream is closed or the official socket for the stream changes. Note that the stream never times out. Data is added to the voice stream by calling VoiceStream.Put.

Put in VoiceStreamBasicImpl.mesa: This procedure adds the bytes from a block to the end of the voice stream.

In VoiceStreamSocketImpl.mesa: This procedure runs the second process for each connection between Bluejay and an Etherphone. It is responsible for sending voice to the Etherphone via the network. VoiceStream.Get is called to see if there is any data in the voice stream to be sent.

Get in VoiceStreamBasicImpl.mesa: This procedure adds the bytes from the end of the voice stream to a given block.

Suppose that a client wants to playback an interval of an existing tune, and that the voice stream is currently idle.

The client calls

Note that the encryption key for this tune must have been previously registered and an associated keyIndex assigned (see ThParty.RegisterKey). Note also that since a chirp contains 8000 voice samples the specified interval in this example overlaps three chirps.

AddPiece allocates a VoiceStream.PieceObject and adds it to the end of the piece queue (in this case it's the only thing on the queue since the voice stream was initially idle). It thens notifies the server.

The server wakes up, finds the server and client queues empty, and starts to work on the new piece. It calls the notify procedure to indicate that the piece has been $started.

The server discovers that the specified interval starts in the middle of the tune's first chirp and that the whole tail of this chirp is needed. The server reads the chirp from the Jukebox into the first buffer on the idle queue. It then uses the chirp's run data to find where the 800th sample starts in the chirp's storage block. This information is recorded in the buffer and the buffer is moved to the client queue. The piece.intervalSpec is updated to be [tuneID: 29, start: 8000, length: 8800, keyIndex: 1].

The server then loops around and discovers that the interval left to be processed starts on a chirp boundary and contains the complete chirp. It reads the chirp from the Jukebox into the first buffer on the idle queue and then moves the buffer to the client queue. The piece.intervalSpec is updated to be [tuneID: 29, start: 16000, length: 800, keyIndex: 1].

The server then loops around once again. This time it discovers that only the first part of a chirp is desired. Nevertheless, it reads the whole chirp from the Jukebox into the first buffer on the idle queue and gives the buffer to the client queue. The piece.intervalSpec is updated to be [tuneID: 29, start: 16800, length: 0, keyIndex: 1].

The next time around, the server notices that the piece has been completely buffered and waits.

Meanwhile, the SendProc's call to VoiceStream.Get succeeds in finding a buffer on the client queue. The non-silent data in the buffer is copied into packets and sent on the network. When the buffer is used up, it is passed back to the server by placing it on the server queue. This procedure is identical for all three buffers.

When the server finds buffers on the server queue, it simply moves them to the idle queue.

When all of the buffers have been replaced on the idle queue, that is the server and client queues are empty, the server concludes that the piece has been completely processed. It thens calls the notify procedure to indicate that the piece has been $finished and removes the piece from the piece queue.

Suppose that a client wants to record a new tune, and that the voice stream is currently idle.

The client calls

Note that the tune must exist and must be closed before calling AddPiece (however the size of the existing tune is unimportant). A new tune can be created by calling Jukebox.CreateTune.

AddPiece allocates a VoiceStream.PieceObject and adds it to the end of the piece queue (in this case it's the only thing on the queue since the voice stream was initially idle). It thens notifies the server.

The server wakes up, finds the server and client queues empty, and starts to work on the new piece. It calls the notify procedure to indicate that the piece has been $started.

The server discovers that the specified interval starts on a chirp boundary and uses the whole chirp. It simply passes an empty buffer, which indicates that it should be filled with a chirp's worth of data destined for the Jukebox, from the idle queue to the client queue. The piece.intervalSpec is updated to be [tuneID: 54, start: 8000, length: VoiceStream.wholeTune].

The server continues this until it runs out of idle buffers or a buffer is returned to the server queue.

Meanwhile, the ReceiveProc's call to VoiceStream.Put succeeds in finding a buffer on the client queue that is destined for the Jukebox. Data from packets received over the network is copied into the buffer. When the buffer is full, it is passed back to the server by placing it on the server queue. The ReceiveProc then attempts to fill another buffer.

When the server discovers a buffer on the server queue that is destined for the Jukebox, it writes the buffer's data block into the appropriate chirp in the Jukebox. It then moves the buffer to the idle queue. Since the piece has not been completely processed, this buffer is immediately set up to receive the next chirp and passed back to the client queue.

This procedure of passing buffers back and forth between the server and the receiving process continues indefinitely until the client calls

FlushPieces simply marks the piece as being flushed. It also calls the notify procedure to indicate that the piece has been $flushed.

When the server notices that the piece is being flushed, it sets piece.intervalSpec.length to zero so that the piece looks like it has been completed. When the ReceiveProc notices the flush, it immediately gives its buffers back to the server. The server then continues to write out buffers that contain data for the Jukebox (these are buffers that were filled before the call to FlushPieces).

When all of the buffers have been replaced on the idle queue, that is the server and client queues are empty, the server concludes that the piece has been completely processed. It thens calls the notify procedure to indicate that the piece has been $finished and removes the piece from the piece queue.