The os_tcp_connector class implements the strategy for initiating a connection and executing a connect handler when the connection is established. The connection can be initiated synchronously or asynchronously. The class os_dispatcher is used for asynchronous connection completion notifications.

The connect() method is used to connect to a server socket with a particular address. If the connection mode is os_tcp_connector::sync , the calling thread blocks until the connection is established. If the connection mode is os_tcp_connector::async the calling thread will not block if the connection cannot be made immediately and an internal connection completion handler is registered with the dispatcher which is notified when the connection competes. The type of the connection handler and its execution strategy can be specified as template instantiation parameters to the connect() method.

The ConnectHandler , the first template parameter, requires a class to have following public interface.

os_tcp_socket& tcp_socket() -Used by the os_tcp_connector object to establish a communication endpoint with the server application.
void* run() -Called by the Executor object to initiate service requests for the server application.

Alternately, the ConnectHandler object could inherit from os_handler_stream class for the os_tcp_socket member data and os_tcp_socket& tcp_socket() member function, thereby not requiring to implement that functionality directly in its own class. The ConnectHandler object should delete itself in void* run()after it is done requesting services from the server.

The Executor , the second template parameter, can be passed one of three concurrency strategy implementations provided (os_same_thread_executor , os_new_thread_executor , and os_thread_pool_executor ) or a custom implementation with the following public interface.

template< class ServiceHandler > void execute( ServiceHandler* handler ) -Calls the void* run() method of the ConnectHandler within the thread context specified by the Executor concurrency strategy.

The os_tcp_acceptor , os_tcp_connector , and os_dispatcher classes can be collectively used to synchronously or asynchronously establish connections and perform service processing at the two connection endpoints.

This class is implemented based on the Acceptor-Connector pattern described in the paper - "Acceptor-Connector - An Object Creational Pattern for connecting and Initializing Communication Services" by Douglas C. Schmidt published in the book "Pattern Languages of Program Design 3", Addison-Wesley 1997.

Use of member template feature in the connect method gives the flexibility of not having the various classes to inherit from a specific interface class. Therefore, the compiler must be able to support member templates and OS_ENABLE_MEMBER_TEMPLATE_FEATURES must be defined to use this class.

Enums


    enum os_tcp_connector::connect_mode
  {
  sync,
  async
  };

Interface

Constructor

os_tcp_connector( os_dispatcher* dispatcher )

Constructs a connector with dispatcher set to dispatcher (default 0 ). The dispatcher argument should be non-zero if connections are made in asynchronous mode in the connect() method.

connect

template< class ConnectHandler, class Executor >

void connect( ConnectHandler* handler , const os_socket_address& address , Executor* executor , connect_mode mode )

Initiates connection and executes connection handler upon connection establishment. Connects to the server socket with address address . After the connection is made, the handler object's

void*
    run()

method is executed using the concurrency strategy specified by executor . If mode is os_tcp_connector::sync (default), the calling thread blocks until the connection is established. If mode is os_tcp_connector::async , the calling thread will not block if the connection cannot be completed immediately and a completion handler is registered with the dispatcher which will later have the executor execute the handler 's void* run() method after the connection completes. For asynchronous connection errors, the handler in its

void*
    run()

method should first check to see if the socket was connected using the connect() method of os_tcp_socket class and, if it is not connected, get the pending error using the get_and_clear_error() member function of the os_socket class. If there is a system call failure, then an exception is thrown.

Throws: os_security_toolkit_error

tcp_connector

Library

Declaration

Enums

Interface