NAME¶
rpcbuf - streambuf specialized for sending and receiving RPC requests
SYNOPSIS¶
#include <Dispatch/rpcbuf.h>
DESCRIPTION¶
An rpcbuf is a streambuf specialized in two ways: to use an IPC connection as a
source or sink of characters and to send and receive RPC requests. The rpcbuf
encloses RPC requests in packets which begin with a length field so that the
rpcbuf can buffer requests until they are complete if the user uses
non-blocking I/O.
CONSTRUCTORS¶
- rpcbuf(iostreamb* = nil)
- Construct an unopened rpcbuf, giving it a pointer to an
iostreamb so that the rpcbuf can read and write the length field of RPC
requests.
IPC OPERATIONS¶
- const char* host()
- int port()
- int fd()
- boolean opened()
- boolean nonblocking()
- Return information about the IPC connection.
- enum { anyport = 0 }
- rpcbuf* listen(int port)
- Create a socket, bind the socket to a <localhost,
port> address, and prepare to accept incoming connections. anyport can
be used in place of a specific port number. Return the rpcbuf's address if
successful, nil otherwise.
- rpcbuf* connect(const char* host, int port)
- Create a socket and connect it to a peer at the <host,
port> address. Return the rpcbuf's address if successful, nil
otherwise.
- rpcbuf* accept(int& fd)
- Accept an incoming connection, allocate a new file
descriptor for it, and assign the new file descriptor to the parameter.
Return the rpcbuf's address if successful, nil otherwise. Can be called
only for rpcbufs that have already called listen.
- rpcbuf* attach(int fd)
- Attach the rpcbuf to a file descriptor. The rpcbuf will not
be allowed to close the file descriptor.
- rpcbuf* nonblocking(boolean)
- Enable or disable non-blocking I/O on the file descriptor
(disabled by default).
- rpcbuf* verbose(boolean)
- Enable or disable printing of error messages when anything
goes wrong (enabled by default).
- rpcbuf* close()
- Flush the get and put areas, close the file descriptor if
it was created by the rpcbuf, and detach the rpcbuf from the file
descriptor.
RPC OPERATIONS¶
- int start_request()
- If a current request exists, compute its length and insert
the length into the request's length field. Then start a new request,
making sure to leave space for the request's length field. Return 0 if no
problem occurred, EOF otherwise.
- int read_request()
- Return 0 if a complete request is buffered in the get area,
EOF otherwise. The rpcbuf moves the get pointer back to the beginning of
the request after extracting the length field and checking that the get
area contains that many bytes.
STREAMBUF OPERATIONS¶
- virtual int overflow(int c=EOF)
- If given EOF, terminate the current request. Flush all
requests buffered in the put area except for the last request if it's
still incomplete. Shift any still incomplete request to the beginning of
the put area. If given a character, append it to the request.
- virtual int underflow()
- Flush the put area. Shift any still unread or incomplete
requests to the beginning of the get area and position the get pointer at
the beginning of the get area. Read as much data as available to fill the
rest of the get area. Return the get area's first character or EOF if a
problem occurred.
- virtual int sync()
- Discard any still unread requests from the get area. Flush
all buffered requests from the put area.
- virtual streampos seekoff(streamoff, ios::seek_dir,
int)
- Allow the user to find the get pointer's current position
so the user can compute how many bytes the get pointer moved between calls
to seekoff. Return EOF if the user tries to do anything else than find the
get pointer's current position.
- virtual streambuf* setbuf(char*, int)
- Reject any attempt to set the buffer used to store incoming
and outgoing requests. The rpcbuf dynamically allocates separate buffers
for both areas and automatically resizes the buffers whenever
necessary.
SEE ALSO¶
IOS.INTRO(3C++), rpcstream(3I)