All Packages  This Package  Class Hierarchy  Class Search  Index

java.lang.Object
   |
   +----utah.npm.core.IPC

Summary

public final class  IPC
     extends java.lang.Object
{
          // Fields 10
     public static final int RC_ACK_DISCONNECTED;
     public static final int RC_CONNECT_INVALIDDEST;
     public static final int RC_OK;
     public static final int RC_OVER_DISCONNECTED;
     public static final int RC_RECV_DISCONNECTED;
     public static final int RC_RECV_MOREDATA;
     public static final int RC_RECV_MOREOBJS;
     public static final int RC_RECV_MOREREFS;
     public static final int RC_RECV_REVERSED;
     public static final int RC_SEND_DISCONNECTED;

          // Constructors 1
     private IPC();

          // Methods 24
     public static final int clientAckSend(IPCPayload);
     public static final int clientAckSendOverReceive(IPCPayload);
     public static final int clientAlert();
     public static final int clientConnectSend(Reference, IPCPayload);
     public static final int clientConnectSendOverReceive(Reference, IPCPayload);
     public static final int clientDisconnect();
     public static final int clientOverReceive(IPCPayload);
     public static final int clientReceive(IPCPayload);
     public static final int clientSend(IPCPayload);
     public static final int clientSendOverReceive(IPCPayload);
     static final int s_clientConnectSendOverReceive(Link, IPCPayload);
     private static final int s_followPortRef(ThreadIPC, Reference);
     public static final int serverAckSend(IPCPayload);
     public static final int serverAckSendOverReceive(IPCPayload);
     public static final void serverAckSendWaitReceive(IPCPayload, IPCWaitReceiveReturn);
     public static final int serverAlert();
     public static final int serverDisconnect();
     public static final int serverOverReceive(IPCPayload);
     public static final int serverReceive(IPCPayload);
     public static final int serverSend(IPCPayload);
     public static final int serverSendOverReceive(IPCPayload);
     public static final void serverSendWaitReceive(IPCPayload, IPCWaitReceiveReturn);
     public static final void serverSetupWaitReceive(IPCPayload, PortSet, IPCWaitReceiveReturn);
     public static final void serverWaitReceive(IPCPayload, IPCWaitReceiveReturn);

}

The "user-visible" IPC API. This class is not instantiable and only has static final methods in it. The IPC semantics are those described in the Fluke documentation. There are separate client and server interfaces. Generally, the "server" is the thread that waits for connections, and the "client" is the one that initiates a request. Connections are established from a "port reference" to a "port". Connections are half-duplex and reversible. Under the hood, all of the IPC operations (beyond establishing the connection) are operations on the per-thread IPC state. All of the operations return an integer status code to indicate the state of the operation (success, or the specific sort of failure).

See Also: Port, Reference, ThreadIPC

Fields

· RC_OK

Summary  |  Top

   public static final int RC_OK

Return code used to indicate success in the operation.

   public static final int RC_CONNECT_INVALIDDEST

Return code used to indicate that the port the client tried to connect to was destroyed.

   public static final int RC_ACK_DISCONNECTED

Return code used to indicate a disconnection during the current thread's ACK phase of its current IPC call.

   public static final int RC_SEND_DISCONNECTED

Return code used to indicate a disconnection during the current thread's SEND phase of its current IPC call.

   public static final int RC_OVER_DISCONNECTED

Return code used to indicate a disconnection during the current thread' OVER phase of its current IPC call.

   public static final int RC_RECV_DISCONNECTED

Return code used to indicate a disconnection during the current thread's RECV phase if its current IPC call.

   public static final int RC_RECV_MOREDATA

Return code used to indicate the current thread does not have enough allocated IPC buffer space for the sender's data. What data could fit in the the current thread's receive buffer has been transferred.

See Also: IPCPayload

   public static final int RC_RECV_MOREREFS

Return code used to indicate the current thread does not have enough allocated IPC buffer space for the sender's references. What data could fit in the the current thread's receive buffer has been transferred.

See Also: IPCPayload

   public static final int RC_RECV_MOREOBJS

Return code used to indicate the current thread does not have enough allocate IPC buffer space for the sender's raw object references. What data could fit in the the current thread's receive buffer has been transferred.

See Also: IPCPayload

   public static final int RC_RECV_REVERSED

Return code used to indicate the current thread's receive operation completed and the connection was reversed before returning to the caller. This return code does not (generally) indicate an error and ususually means the sender transferred all of its data and reversed the connection in anticipation of receving a reply.

See Also: IPCPayload

Constructors

· IPC

Summary  |  Top

   private IPC() 

Private constructor to prevent instantiation of this class.

   private static final int s_followPortRef(ThreadIPC clientIPC, 
                                            Reference portRef) 

Convert a portRef into the state necessary for an IPC client to initiate a connection. If this function is changed, be sure to update s_clientConnectSendOverReceive() also.

Parameter	Description
clientIPC	the client thread's IPC state
portRef	a reference to an NPM port object.

Returns:

0 if it worked, non-zero error code if not.

See Also: ThreadIPC

   public static final int clientConnectSend(Reference destPortRef, 
                                             IPCPayload payload) 

Perform a connect to the provided port and send the provided payload to a waiting server. If no server is currently available this call blocks until one is. The current thread's (hidden) client state will be setup to reflect this connection.

Parameter	Description
destPortRef	a Reference to a Port to rendezvous at with a server thread
payload	the payload to send to the server thread

Returns:

an integer return code describing the state of the connection.

   public static final int clientAckSend(IPCPayload payload) 

Reverse the current thread's connection with a sever and send the provided payload. The client must have previously established the connection with a server thread.

Parameter	Description
payload	the payload to send to the connected server thread.

Returns:

an integer return code describing the state of the connection.

   public static final int clientSend(IPCPayload payload) 

Send data on the current thread's connection with a server. Does not reverse the connection or wakeup the server (unless the server's buffers are full.)

Parameter	Description
payload	the payload to send to the connected server thread.

Returns:

an integer return code describing the state of the connection.

   public static final int clientConnectSendOverReceive(Reference destPortRef, 
                                                        IPCPayload payload) 

Connect the current thread to a server through the provided port reference, send the payload data, reverse the connection, wait for, and receive a response from the server. In the payload, the send and recive buffers can be the same actual buffer.

Parameter	Description
destPortRef	a reference to a port to rendezvous at with a server thread.
payload	the payload to send to the connected server thread and to recieve a reply into

Returns:

an integer return code describing the state of the connection.

   static final int s_clientConnectSendOverReceive(Link portLink, 
                                                   IPCPayload payload) 

This is a special (hackish) interface to the IPC system used by other NPM Space object (in particular the Space and MemPool) They have internal Links pointing to the port objects they need to connect to. Instead of fabricating an extra Reference object, this special interface is provided. This function duplicates parts of s_followPortRef. See Space.classNameException() and MemPool.outOfMemoryException() for how/where this function is used.

Parameter	Description
portLink	the Link to the Port object to connect to
payload	the request to send and the buffer to receive the reply into

Returns:

an integer return code describing the state of the connection

See Also: s_followPortRef, Space.classNameException, MemPool.outOfMemoryException

   public static final int clientAckSendOverReceive(IPCPayload payload) 

Reverse the current thread's connection to a server, send a request, and wait for and receive a reply. In the payload, the send and receive buffers can be teh same actual buffer.

Parameter	Description
payload	the payload to send to the connected server thread and to receive a reply into

Returns:

an integer return code describing the state of the connection.

   public static final int clientSendOverReceive(IPCPayload payload) 

Send a request to the current thread's server, reverse the connection, wait for and receive a reply. In the payload, the send and receive buffers can be teh same actual buffer.

Parameter	Description
payload	the payload to send to the connected server thread and to receive a reply into

Returns:

an integer return code describing the state of the connection.

   public static final int clientOverReceive(IPCPayload payload) 

Reverse the current thread's server connection and wait for and receive a reply.

Parameter	Description
payload	the payload to receive the server's reply into

Returns:

an integer return code describing the state of the connection.

   public static final int clientReceive(IPCPayload payload) 

Receive more data from the current thread's server.

Parameter	Description
payload	the payload to receive the data from the server into

Returns:

an integer return code describing the state of the connection.

   public static final int clientDisconnect() 

Disconnect the current thread's connection to its server.

Returns:

an integer return code describing the state of the connection.

   public static final int clientAlert() 

Send an alert to the current threads server thread. TODO: Not implemented.

Returns:

an integer return code describing the state of the connection.

   public static final int serverAckSend(IPCPayload payload) 

Reverse the current thread's connection to a client and send a reply.

Parameter	Description
payload	the payload to send to the connected client thread.

Returns:

an integer return code describing the state of the connection.

   public static final int serverSend(IPCPayload payload) 

Send a reply to the current thread's client.

Parameter	Description
payload	the payload to send to the connected client thread.

Returns:

an integer return code describing the state of the connection.

   public static final void serverAckSendWaitReceive(IPCPayload payload, 
                                                     IPCWaitReceiveReturn out_rc) 

Reverse the direction of the current thread's connection to its client, send a reply and wait for a new request from any client. (There is an implicit disconnect from the client thread). To maintain the connection with the current client use serverAckSendOverReceive().

Parameter	Description
payload	the payload to send to the connected client thread and receive a new request into
out_rc	(output) the integer return code describing the state of the connection and (if a new connection was established) the port alias of the port the new client thread connected on.

See Also: serverAckSendOverReceive

   public static final int serverAckSendOverReceive(IPCPayload payload) 

Reverse the direction of the current thread's connection to its client, send a reply and wait for a new request from this client. To wait for and connect to a new client thread after sending this reply, use serverAckSendWaitReceive().

Parameter	Description
payload	the payload to send to the connected client thread and receive its next request into

Returns:

an integer return code describing the state of the connection.

See Also: serverAckSendWaitReceive

   public static final void serverSetupWaitReceive(IPCPayload payload, 
                                                   PortSet pset, 
                                                   IPCWaitReceiveReturn out_rc) 

Setup the current thread as a server on the provided PortSet and wait for new client connections on any Port in that PortSet.

Parameter	Description
payload	the payload to receive a new client's request into.
pset	the set of port objects this thread will accept connection on.
out_rc	(output) the integer return code describing the state of the connection and (if a new connection was established) the port alias of the port the new client thread connected on.

   public static final void serverWaitReceive(IPCPayload payload, 
                                              IPCWaitReceiveReturn out_rc) 

The current thread will wait for new client threads on its implied port set (from the previous call to serverSetupWaitReceive().

Parameter	Description
payload	the payload to receive a new client's request into
out_rc	(output) the integer return code describing the state of the connection and (if a new connection was established) the port alias of the port the new client thread connected on.

See Also: serverSetupWaitReceive

   public static final void serverSendWaitReceive(IPCPayload payload, 
                                                  IPCWaitReceiveReturn out_rc) 

Send a reply to the current thread's client, disconnect and wait for a new client connection on the current thread's implied PortSet (from its previous call to serverSetupWaitReceive()). To maintain the connection with the current client use serverSendOverReceive()

Parameter	Description
payload	the payload to send to the client and receive a new client's request into
out_rc	(output) the integer return code describing the state of the connection and (if a new connection was established) the port alias of the port the new client thread connected on.

See Also: serverSetupWaitReceive, serverSendOverReceive

   public static final int serverSendOverReceive(IPCPayload payload) 

Send a reply to the current thread's client, reverse the direction of the connection and wait for a new request from the same client. To disconnect from the current client and wait for a new request from any client connecting to the current thread's implied PortSet, use serverSendWaitReceive().

Parameter	Description
payload	the payload to send to the connected client thread and receive its next request into

Returns:

an integer return code describing the state of the connection.

See Also: serverSendWaitReceive

   public static final int serverOverReceive(IPCPayload payload) 

Reverse the direction of the current thread's client connection and wait for a new request from that client.

Parameter	Description
payload	the payload to receive the client next request into

Returns:

an integer return code describing the state of the connection.

   public static final int serverReceive(IPCPayload payload) 

Receive more data from the current thread's client thread.

Parameter	Description
payload	the payload to receive more data from the client into

Returns:

an integer return code describing the state of the connection

   public static final int serverDisconnect() 

Disconnect the current thread from its client.

Returns:

an integer return code describing the state of the connection.

   public static final int serverAlert() 

Send an alert to the current thread's client thread. TODO: Not implemented yet.

Returns:

an integer return code describing the state of the connection.

All Packages  This Package  Class Hierarchy  Class Search  Index