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.