Reference: Communications
General
The communications interface is
closely linked to token trees to allow you to serialize
and stream these for interprocess communication. It connects with the sockets
subsystem for stream management. In the communications context, token trees
are often referred to as "blocks". A block constitutes one root node and
its recursive children.
Properties overview
- Has two ends, one remote
and one local to the process.
- Is streamed.
- Is bidirectional.
- Is buffered.
- Has queue-oriented buffers
for trees, before/after serializing.
- Can connect two processes
on the same machine and in the same process group, through pipes.
- Can connect two processes
on different machines, through TCP/IP.
- When the result of an incoming
connection, indicates which parent comm that spawned it.
Non-blocking operation
To do non-blocking reads/writes
with a COMM, you have to register it with a PROXY
and use queuing operations. The actual transfer functions documented here
are for simple programs that can afford to block, or threaded implementations.
Allocation
- COMM
*comm_new();
Creates a new, unconnected TCP/IP comm, with an automatically assigned
port. It does not accept incoming connections.
- COMM
*comm_pipe_new();
Creates a new loopback pipe with comm infrastructure. In its initial
state, all data you send to it is buffered and sent back to you.
- COMM
*comm_new_with_port(int port);
Creates a new, unconnected comm and binds it to a specific port (port). It does not accept incoming connections. This might be
useful if the other end expects connections to come from a specific
port on your host. Otherwise, you should just use comm_new.
- COMM
*comm_accepting_new(int port);
Creates a new, unconnected comm and binds it to port.
It will accept incoming connections.
- COMM
*comm_new_with_sock(SOCK *s);
Assigns comm infrastructure to an existing socket. The socket must not
be in the process of exchanging data.
- void
comm_del(COMM *c);
Disconnects and frees any kind of COMM, specified
by c.
Queuing
- int comm_enqueue(COMM *c, TT *block, u16 trans, u32 flags);
Queues TT block to comm c
with transaction number trans (0 for default) and flags flags
for sending. Should be used in all non-blocking communications.
Supported values for flags:
COMM_ORDER_BREADTH_FIRST: Serializes block breadth-first. Depth-first is the default.
COMM_ORDER_DEPTH_FIRST: Serializes block depth-first. This is the default.
- TT *comm_dequeue(COMM *c, int *trans);
Dequeues the next incoming TT from c, storing
its transaction number in trans. Returns the
root of the tree, or NULL if there are none
pending.
- int comm_queue_out_len(COMM *c);
Gives the number of trees (blocks) queued for sending on c. The block currently being sent is not counted.
- int comm_queue_in_len(COMM *c);
Gives the number of trees (blocks) queued for reading on c. The block currently being received is not counted.
Blocking I/O
- void comm_flush(COMM *c);
Blocks until all outgoing data queued/buffered in c
is sent.
- void comm_send(COMM *c, TT *tt);
Blocks until all outgoing data queued/buffered in c,
as well as the block provided as tt, is sent.
- void comm_send_with_flags(COMM *c, TT *tt,
u16 flags);
Blocks until all outgoing data queued/buffered in c,
as well as the block provided as tt, is sent.
This call lets you specify optional modes for the transmission.
Supported values for flags:
COMM_ORDER_BREADTH_FIRST: Serializes block breadth-first. Depth-first is the default.
COMM_ORDER_DEPTH_FIRST: Serializes block depth-first. This is the default.
- void comm_send_with_trans(COMM *c, TT *tt,
u16 trans);
Blocks until all outgoing data queued/buffered in c,
as well as the block provided as tt, is sent.
This call lets you specify a transaction number for the block. Set it
to 0 for none (although in that case, you would probably want to use
plain comm_send() instead).
- void comm_send_with_trans_and_flags(COMM *c, TT *tt,
u16 trans, u16 flags);
Blocks until all outgoing data queued/buffered in c,
as well as the block provided as tt, is sent.
This call lets you specify a transaction number and optional modes for
the transmission. See comm_send_with_trans() and comm_send_with_flags()
for more details.
- TT *comm_recv(COMM *c);
Gets the next incoming block from c's queue,
or, if the queue is empty, waits indefinitely for one to arrive (or
the stream closing). Returns the fetched block, or NULL
if nothing could be read because the stream (was) closed.
- TT *comm_recv_with_trans(COMM *c, u16 *trans);
Gets the next incoming block from c's queue,
or, if the queue is empty, waits indefinitely for one to arrive (or
the stream closing). Returns the fetched block, or NULL
if nothing could be read because the stream (was) closed. Stores the
transaction number for the fetched block, in trans.
0 is the default transaction.
Status information
- int comm_buf_out_size(COMM *c);
Gives the size of the outgoing stream buffer for c.
In general, you don't have to worry about this. Used internally.
- int comm_buf_in_size(COMM *c);
Gives the size of the incoming stream buffer for c.
In general, you don't have to worry about this. Used internally.
- SOCK *comm_get_sock(COMM *c);
Returns the socket used for c's streamed transmission.
- int comm_get_fd_read(COMM *c);
Returns the file descriptor used to read from c's
stream. You won't have much use for this, unless you're working on Flux
internals.
- int comm_get_fd_write(COMM *c);
Returns the file descriptor used to write to c's
stream. You won't have much use for this, unless you're working on Flux
internals.
- u16 comm_get_trans_in(COMM *c);
Returns the transaction number of block being received.
- u16 comm_get_trans_out(COMM *c);
Returns the transaction number of block being sent.
- int comm_is_connecting(COMM *c);
Returns TRUE if the comm is currently trying
to establish an outgoing connection (asynchronously).
- int comm_is_connected(COMM *c);
Returns TRUE if the comm is connected at
the remote end.
- int comm_is_accepting(COMM *c);
Returns TRUE if the comm will accept an incoming
connection attempt.
- int comm_is_active(COMM *c);
Returns TRUE if the comm is either connected
or available for incoming connections.
Arbitrary limits
- void
comm_limits(COMM *c, u32 nodes, u32 size, u32 depth);
Sets limits to protect you from flooding or maliciously malformed trees.
You should set this a good bit higher than the maximums you expect (nonconforming
blocks will be dropped silently). This can also be changed underway,
i.e. after authentication of the remote end. nodes
represents the maximum number of nodes a tree can contain, size is the maximum amount of total data in the tree, and depth
is the highest depth any node in the tree can have. These parameters
are set pretty low by default, so changing them to match your requirements
is a good idea.
|