SSF.OS.TCP
Class tcpSocket

java.lang.Object
  |
  +--SSF.OS.ProtocolSession
        |
        +--SSF.OS.TCP.tcpSocket

All Implemented Interfaces:

com.renesys.raceway.DML.Configurable, socketAPI

public class tcpSocket

extends ProtocolSession

implements socketAPI

BSD-style TCP socket pseudoprotocol for implementing protocols and applications that use TCP transport.

Field Summary

int	dest_ip_addr
int	destination_port
tcpSocket	listeningSocket If the socket was created by a listening socket in response to a connection request, contains the reference to the listening socket.
int	source_ip_addr
int	source_port

Fields inherited from class SSF.OS.ProtocolSession

name, use

Constructor Summary

tcpSocket(ProtocolSession caller, socketMaster sm)
Creates an unconnected, unnamed TCP socket.

Method Summary

void	abort() User aborts the connection.
void	accept(socketAPI[] new_socket, Continuation caller) Accept a socket from the complete socket queue.
void	addConnection(tcpSocket sock) Informs the listening socket that a pending connection request has become an established connection ready to be accepted.
tcpSocket	addSocket(int src_port, int dest_ip, int dest_port) If this is a listening socket, returns a new socket created in response to received connection request.
void	bind(int src_ip, int src_port) Bind the socket to a local port number and IP address.
void	bindTcpSession(tcpSession tcpSess) Bind a tcpSession to this socket.
void	close(Continuation caller) Close a socket and release all its resources.
void	connect(int remote_ip, int remote_port, Continuation caller) Active open a TCP connection.
void	connected() TCP calls it to indicate a connection has opened successfully
void	disconnected() Callback from tcpSession when an established connection is disconnected.
void	failure(int error) Called by tcpSession.drop() when connection is dropped (drop() removes the tcpSession bound to the socket).
void	listen(int Qlimit) Passive open a TCP session and listen on the port bound to the socket for incoming connection requests.
boolean	push(ProtocolMessage message, ProtocolSession fromSession) No-op, returns false.
void	read(byte[] buf, int nbytes, Continuation caller) not supported by tcp sockets
void	read(int nbytes, Continuation caller) Read nbytes of virtual data.
void	read(java.lang.Object[] obj, int nbytes, Continuation caller) Read a reference to an object whose nominal size is nbytes.
boolean	removeFromQueue(tcpSocket sock) If TCP connection bound to socket sock is dropped, and sock is still in the listening socket's queue, remove sock from the queue.
void	socketInfo(java.lang.String str) Socket diagnostics message formatting.
void	write(byte[] buf, int nbytes, Continuation caller) not supported for tcp sockets
void	write(int nbytes, Continuation caller) Write nbytes bytes of virtual data.
void	write(java.lang.Object[] obj, int nbytes, Continuation caller) Write an application-level object to be transmitted.

Methods inherited from class SSF.OS.ProtocolSession

close, closed, config, debugIdentifier, inGraph, init, open, opened, pushAfterDelay, pushAfterDelayFailed, setGraph, version

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

listeningSocket

public tcpSocket listeningSocket

If the socket was created by a listening socket in response to a connection request, contains the reference to the listening socket. Used by tcpSession to inform the listening socket about processing of the pending request. Used by an incomplete socket if connection was dropped to get removed from the incomplete socket queue by its listening socket.

source_ip_addr

public int source_ip_addr

dest_ip_addr

public int dest_ip_addr

destination_port

public int destination_port

source_port

public int source_port

Constructor Detail

tcpSocket

public tcpSocket(ProtocolSession caller,
                 socketMaster sm)

Creates an unconnected, unnamed TCP socket. It is recommended to use SSF.OS.Socket.socketMaster.socket() to create a socket.

Method Detail

socketInfo

public void socketInfo(java.lang.String str)

Socket diagnostics message formatting.

bind

public void bind(int src_ip,
                 int src_port)

Bind the socket to a local port number and IP address.

A socket user acting as client need not care about local IP address, if it is left undefined then the IP protocol will set it to the address of the interface used to send the TCP/IP messages out. In contrast, a well-known local address and port must be bound to a server socket before it can listen for connection requests.

Specified by:

bind in interface socketAPI

Parameters:

src_ip - local IP address

src_port - local port number

bindTcpSession

public void bindTcpSession(tcpSession tcpSess)

Bind a tcpSession to this socket. Callback from tcpSessionMaster in response to active or passive open request.

failure

public void failure(int error)

Called by tcpSession.drop() when connection is dropped (drop() removes the tcpSession bound to the socket). If a blocking socket method is in progress, invokes the failure(errno) method of the Continuation that simulates the blocking.

push

public boolean push(ProtocolMessage message,
                    ProtocolSession fromSession)
             throws ProtocolException

No-op, returns false. Required by ProtocolSession interface.

Specified by:

push in class ProtocolSession

ProtocolException

listen

public void listen(int Qlimit)

Passive open a TCP session and listen on the port bound to the socket for incoming connection requests.

SSF.OS.TCP implements the pending request queue management in the BSD style: the incoming connection requests are rejected if the sum of the number of pending incomplete connections (i.e. before the TCP 3-way handshake is completed) and of the number of pending established connections (i.e. not yet accepted by server) is greater than 1.5*Qlimit.

Note that different operating systems implement the request queue managment differently, for instance in Linux 2.2 the argument Qlimit specifies the queue length for completely established sockets waiting to be accepted, while the maximum length of the queue for incomplete sockets can be set using a separate method call.

Specified by:

listen in interface socketAPI

Parameters:

Qlimit - For tcpSocket, specifies the maximum number of connection requests pending accept. Ignored by udpSocket.

addSocket

public tcpSocket addSocket(int src_port,
                           int dest_ip,
                           int dest_port)
                    throws ProtocolException

If this is a listening socket, returns a new socket created in response to received connection request. The new socket is put in the incomplete socket queue. Returns null if the pending request queue is larger than that specified by the Qlimit parameter in the listen() call that set up this listening socket.

Called by tcpSessionMaster when a connection request (SYN) arrives to a passively opened tcpSession.

ProtocolException

addConnection

public void addConnection(tcpSocket sock)

Informs the listening socket that a pending connection request has become an established connection ready to be accepted.

accept

public void accept(socketAPI[] new_socket,
                   Continuation caller)
            throws ProtocolException

Accept a socket from the complete socket queue.

Continuation.success() callback is invoked when a complete socket is available.

Continuation.failure(errno) callback is invoked if an error condition is encountered.

Failure codes returned by the Continuation caller:

EWOULDBLOCK Socket is non-blocking and no connections are pending.

EINVAL Socket is not listening for connections (e.g., because it was closed before any incoming connection request was completed.

Specified by:

accept in interface socketAPI

Parameters:

new_socket - one-element array that will contain the new connected socket when Continuation returns successfully.

caller - user-defined Continuation specifying the actions to be taken when a connection is either successfully accepted or an error is signalled.

ProtocolException

removeFromQueue

public boolean removeFromQueue(tcpSocket sock)

If TCP connection bound to socket sock is dropped, and sock is still in the listening socket's queue, remove sock from the queue.

connect

public void connect(int remote_ip,
                    int remote_port,
                    Continuation caller)
             throws ProtocolException

Active open a TCP connection. If this socket is not bound to a local port number via bind(), automatically generate the local port number.

If this socket already has an open connection, callback the Continuation with error = EISCONN. If socket is set as a listening socket, callback the Continuation with error = Errors: EISCONN The socket is already connected. ECONNREFUSED No one listening on the remote address. ETIMEDOUT Timeout while attempting connection. EINPROGRESS The socket is non-blocking and the connection cannot be completed immediately.

Specified by:

connect in interface socketAPI

Parameters:

remote_ip - remote IP address

remote_port - remote port number

caller - user-defined Continuation specifying the actions to be taken when a connection is either successfully established or an error is signalled.

ProtocolException

connected

public void connected()

TCP calls it to indicate a connection has opened successfully

close

public void close(Continuation caller)
           throws ProtocolException

Close a socket and release all its resources. On return this socket object is no longer usable as a communications endpoint.

If close a socket when a connection is established, initiate TCP disconnection procedure.

If close a passively listening socket, this method first aborts any pending connections on its connection request queue, returns the Continuation failure for any pending accept() call with failure errno EBADF, and finally returns caller.success().

Specified by:

close in interface socketAPI

Parameters:

caller - the user defined Continuation class which defines the action should be taken when connection is either successfully closed or an error is signalled.

ProtocolException

disconnected

public void disconnected()

Callback from tcpSession when an established connection is disconnected.

abort

public void abort()

User aborts the connection. Not used.

Specified by:

abort in interface socketAPI

write

public void write(java.lang.Object[] obj,
                  int nbytes,
                  Continuation caller)

Write an application-level object to be transmitted. Only object reference is actually sent to the receiver, with nbytes value used to calculate packet sizes (as with virtual data).

Will invoke the caller.success() method after the sent nbytes bytes have been acknowledged; or will invoke the caller.failure(errno) method with appropriate error code if the connection has been dropped.

This is a simulated blocking method, and the write failure will be returned with error EBUSY if an attempt is made to write while the previous write's Continuation has not yet returned.

Specified by:

write in interface socketAPI

Parameters:

obj - Array of size 1, to pass a reference to an object to the message recipient.

nbytes - Nominal size in bytes. For a UDP socket, the object reference is passed in one datagram of size nbytes; for a TCP socket the object reference is sent in the first TCP segment, followed by zero or more segments padded with virtual data, so that the total size is nbytes. In either case, the receipient's matching read() Continuation returns success() only after nbytes were received, and then the reference to the transmitted object becomes available.

caller - user-defined Continuation specifying the actions to be taken when either nbytes of (virtual) data is successfully written or an error is signalled.

write

public void write(byte[] buf,
                  int nbytes,
                  Continuation caller)

not supported for tcp sockets

Specified by:

write in interface socketAPI

Parameters:

nbytes - size of data to be transmitted

caller - user-defined Continuation specifying the actions to be taken when either nbytes of data is successfully written or an error is signalled.

write

public void write(int nbytes,
                  Continuation caller)

Write nbytes bytes of virtual data. This will cause one or more TCP segments to be transmitted, with the total payload size equal to nbytes. Will invoke the caller.success() method after nbytes bytes of virtual data have been acknowledged; or will invoke the caller.failure(errno) method with appropriate error code if the TCP connection has been dropped.

This is a simulated blocking method, and the write failure will be returned with error EBUSY if an attempt is made to write while the previous write's Continuation has not yet returned.

Specified by:

write in interface socketAPI

Parameters:

nbytes - number of bytes of pseudo-data that defines the transmitted payload size

caller - user-defined Continuation specifying the actions to be taken when either nbytes of data is successfully written or an error is signalled.

read

public void read(byte[] buf,
                 int nbytes,
                 Continuation caller)

not supported by tcp sockets

Specified by:

read in interface socketAPI

Parameters:

nbytes - expected received data size

caller - user-defined Continuation specifying the actions to be taken when either all data is read successfully or an error is signalled.

read

public void read(java.lang.Object[] obj,
                 int nbytes,
                 Continuation caller)

Read a reference to an object whose nominal size is nbytes.

Obviously, a pair of application-level protocols using write(obj,...) and read(obj,...) must agree on the interpretation of the transmitted object references. The object itself is NOT copied, and read() provides a reference to the same object that was used to send it via write(obj,...).

Will invoke the caller.success() method after nbytes bytes of virtual data have been received; or will invoke the caller.failure(errno) method with appropriate error code if the TCP connection has been dropped.

This is a simulated blocking method, and the read failure will be returned with error EBUSY if an attempt is made to read while the previous read's Continuation has not yet returned.

Specified by:

read in interface socketAPI

Parameters:

obj - user-defined array whose first element obj[0] will contain the data object if read is successful

nbytes - expected number of received data bytes

caller - user-defined Continuation specifying the actions to be taken when either all data is read successfully or an error is signalled.

read

public void read(int nbytes,
                 Continuation caller)

Read nbytes of virtual data.

Will invoke the caller.success() method after nbytes bytes of virtual data have been received; or will invoke the caller.failure(errno) method with appropriate error code if the TCP connection has been dropped.

This is a simulated blocking method, and the read failure will be returned with error EBUSY if an attempt is made to read while the previous read's Continuation has not yet returned.

Specified by:

read in interface socketAPI

Parameters:

nbytes - expected number of bytes of received pseudo-data

caller - user-defined Continuation specifying the actions to be taken when either all data is read successfully or an error is signalled.