Download
Docs

Contact
About
Docs
CVS

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.

 

 

Flux, these web pages, and all related material are Copyright©1999-2000 Simplemente and the respective authors, and are licensed under the GNU GPL. Please see the About page for more details. Web design by Joakim Ziegler <joakim@simplemente.net>, illustrations by Belinda Laws, <boysdontcry@zombieworld.com>.