---
name: "ACE_Connector"
section: "3"
platform: "linux"
package: "libace-doc"
version: "5.0.7-4"
release: "Debian 2.2 (Potato)"
platforms: ["linux"]
url: "https://new.carta.tech/ACE_Connector"
---

# ACE\_Connector(3)

Generic factory for actively connecting clients and creating service handlers (SVC\_HANDLERs).

## NAME

ACE\_Connector -  Generic factory for actively connecting clients and creating service handlers (SVC\_HANDLERs).

## SYNOPSIS

```
#include <ace/Connector.h>
template<class SVC_HANDLER, ACE_PEER_CONNECTOR_1>
class ACE_Connector : public ACE_Service_Object
{
  public:
    typedef ACE_PEER_CONNECTOR_ADDR ACE_PEER_ADDR_TYPEDEF;
    ACE_Connector (
        ACE_Reactor *r = ACE_Reactor::instance (),
        int flags = 0
        );
    virtual int open (
        ACE_Reactor *r = ACE_Reactor::instance (),
        int flags = 0
        );
    virtual ~ACE_Connector (void);
    virtual int connect (
        SVC_HANDLER *&svc_handler,
        const ACE_PEER_CONNECTOR_ADDR &remote_addr,
        const ACE_Synch_Options &synch_options = ACE_Synch_Options::defaults,
        const ACE_PEER_CONNECTOR_ADDR &local_addr = (ACE_PEER_CONNECTOR_ADDR &) ACE_PEER_CONNECTOR_ADDR_ANY,
        int reuse_addr = 0,
        int flags = O_RDWR,
        int perms = 0
        );
    virtual int connect (
        SVC_HANDLER *&svc_handler_hint,
        SVC_HANDLER *&svc_handler,
        const ACE_PEER_CONNECTOR_ADDR &remote_addr,
        const ACE_Synch_Options &synch_options = ACE_Synch_Options::defaults,
        const ACE_PEER_CONNECTOR_ADDR &local_addr = (ACE_PEER_CONNECTOR_ADDR &) ACE_PEER_CONNECTOR_ADDR_ANY,
        int reuse_addr = 0,
        int flags = O_RDWR,
        int perms = 0
        );
    virtual int connect_n (
        size_t n,
        SVC_HANDLER *svc_handlers[],
        ACE_PEER_CONNECTOR_ADDR remote_addrs[],
        ASYS_TCHAR *failed_svc_handlers = 0,
        const ACE_Synch_Options &synch_options = ACE_Synch_Options::defaults
        );
    virtual int cancel (SVC_HANDLER *svc_handler);
    virtual int close (void);
    void dump (void) const;
    ACE_ALLOC_HOOK_DECLARE;
  protected:
    typedef ACE_Svc_Tuple<SVC_HANDLER> AST;
        typedef ACE_Map_Manager<ACE_HANDLE, ACE_Svc_Tuple<SVC_HANDLER> *, ACE_SYNCH_RW_MUTEX> MAP_MANAGER;

        typedef ACE_Map_Iterator<ACE_HANDLE, ACE_Svc_Tuple<SVC_HANDLER> *, ACE_SYNCH_RW_MUTEX> MAP_ITERATOR;

        typedef ACE_Map_Entry<ACE_HANDLE, ACE_Svc_Tuple<SVC_HANDLER> *> MAP_ENTRY;

    virtual int make_svc_handler (SVC_HANDLER *&sh);
    virtual int connect_svc_handler (
        SVC_HANDLER *&svc_handler,
        const ACE_PEER_CONNECTOR_ADDR &remote_addr,
        ACE_Time_Value *timeout,
        const ACE_PEER_CONNECTOR_ADDR &local_addr,
        int reuse_addr,
        int flags,
        int perms
        );
    virtual int connect_svc_handler (
        SVC_HANDLER *&svc_handler,
        SVC_HANDLER *&sh_copy,
        const ACE_PEER_CONNECTOR_ADDR &remote_addr,
        ACE_Time_Value *timeout,
        const ACE_PEER_CONNECTOR_ADDR &local_addr,
        int reuse_addr,
        int flags,
        int perms
        );
    virtual int activate_svc_handler (SVC_HANDLER *svc_handler);
    virtual int handle_input (ACE_HANDLE);
    virtual int handle_output (ACE_HANDLE);
    virtual int handle_exception (ACE_HANDLE fd = ACE_INVALID_HANDLE);
    virtual int init (int argc, ASYS_TCHAR *argv[]);
    virtual int fini (void);
    virtual int info (ASYS_TCHAR **, size_t) const;
    virtual int handle_close (
        ACE_HANDLE = ACE_INVALID_HANDLE,
        ACE_Reactor_Mask = ACE_Event_Handler::ALL_EVENTS_MASK
        );
    virtual int handle_timeout (
        const ACE_Time_Value &tv,
        const void *arg
        );
    virtual int suspend (void);
    virtual int resume (void);
    int create_AST (SVC_HANDLER *, const ACE_Synch_Options &);
    int cleanup_AST (ACE_HANDLE, AST *&);
    virtual int connect_i (
        SVC_HANDLER *&svc_handler,
        SVC_HANDLER **sh_copy,
        const ACE_PEER_CONNECTOR_ADDR &remote_addr,
        const ACE_Synch_Options &synch_options,
        const ACE_PEER_CONNECTOR_ADDR &local_addr,
        int reuse_addr,
        int flags,
        int perms
        );
    MAP_MANAGER handler_map_;
  private:
    ACE_PEER_CONNECTOR connector_;
    char closing_;
    int flags_;
};
```

## DESCRIPTION

Implements the strategy for actively establishing connections with clients.  An ACE\_Connector is parameterized by concrete types that conform to the interfaces of PEER\_CONNECTOR and SVC\_HANDLER.  The PEER\_CONNECTOR is instantiated with a transport mechanism that passively establishes connections. The SVC\_HANDLER is instantiated with a concrete type that performs the application-specific service.  An ACE\_Connector inherits from ACE\_Service\_Object, which in turn inherits from ACE\_Event\_Handler.  This enables the ACE\_Reactor to dispatch the ACE\_Connector's handle\_output method when connections complete asynchronously.  The handle\_output method performs the connector's active connection establishment and service activation strategy.

## Initialization and termination methods.

typedef ACE\_TYPENAME ACE\_PEER\_CONNECTOR\_ADDR PEER\_ADDR;

```
typedef ACE_PEER_CONNECTOR_ADDR ACE_PEER_ADDR_TYPEDEF;
```

```
ACE_Connector (
    ACE_Reactor *r = ACE_Reactor::instance (),
    int flags = 0
    );
```

Initialize a connector.  flags indicates how SVC\_HANDLER's should be initialized prior to being activated.  Right now, the only flag that is processed is ACE\_NONBLOCK, which enabled non-blocking I/O on the SVC\_HANDLER when it is opened.

```
virtual int open (
    ACE_Reactor *r = ACE_Reactor::instance (),
    int flags = 0
    );
```

Initialize a connector.  flags indicates how SVC\_HANDLER's should be initialized prior to being activated.  Right now, the only flag that is processed is ACE\_NONBLOCK, which enabled non-blocking I/O on the SVC\_HANDLER when it is opened.

```
virtual ~ACE_Connector (void);
```

Shutdown a connector and release resources.

## Connection establishment methods.

```
virtual int connect (
    SVC_HANDLER *&svc_handler,
    const ACE_PEER_CONNECTOR_ADDR &remote_addr,
    const ACE_Synch_Options &synch_options = ACE_Synch_Options::defaults,
    const ACE_PEER_CONNECTOR_ADDR &local_addr = (ACE_PEER_CONNECTOR_ADDR &) ACE_PEER_CONNECTOR_ADDR_ANY,
    int reuse_addr = 0,
    int flags = O_RDWR,
    int perms = 0
    );
```

Initiate connection of svc\_handler to peer at remote\_addr using synch\_options.  If the caller wants to designate the selected local\_addr they can (and can also insist that the local\_addr be reused by passing a value reuse\_addr == 1). flags and perms can be used to pass any flags that are needed to perform specific operations such as opening a file within connect with certain permissions.  If the connection fails the close hook on the svc\_handler will be called automatically to prevent resource leaks.

```
virtual int connect (
    SVC_HANDLER *&svc_handler_hint,
    SVC_HANDLER *&svc_handler,
    const ACE_PEER_CONNECTOR_ADDR &remote_addr,
    const ACE_Synch_Options &synch_options = ACE_Synch_Options::defaults,
    const ACE_PEER_CONNECTOR_ADDR &local_addr = (ACE_PEER_CONNECTOR_ADDR &) ACE_PEER_CONNECTOR_ADDR_ANY,
    int reuse_addr = 0,
    int flags = O_RDWR,
    int perms = 0
    );
```

This is a variation on the previous connect method.  On cached connectors the svc\_handler\_hint variable can be used as a hint for future lookups.  Since this variable is modified in the context of the internal cache its use is thread-safe.  But the actual svc\_handler for the current connection is returned in the second parameter svc\_handler.  If the connection fails the close hook on the svc\_handler will be called automatically to prevent resource leaks.

```
virtual int connect_n (
    size_t n,
    SVC_HANDLER *svc_handlers[],
    ACE_PEER_CONNECTOR_ADDR remote_addrs[],
    ASYS_TCHAR *failed_svc_handlers = 0,
    const ACE_Synch_Options &synch_options = ACE_Synch_Options::defaults
    );
```

Initiate connection of n svc\_handlers to peers at remote\_addrs using synch\_options.  Returns -1 if failure occurs and 0 otherwise.  If failed\_svc\_handlers is non-NULL, a 1 is placed in the corresponding index of failed\_svc\_handler for each svc\_handlers\[i that failed to connect, else a 0 is placed in that index.

```
virtual int cancel (SVC_HANDLER *svc_handler);
```

Cancel a svc\_handler that was started asynchronously. Note that this is the only case when the Connector does not actively close the svc\_handler. It is left up to the caller of cancel to decide the fate of the svc\_handler.

```
virtual int close (void);
```

Close down the Connector

```
void dump (void) const;
```

Dump the state of an object.

```
ACE_ALLOC_HOOK_DECLARE;
```

Declare the dynamic allocation hooks.

## Helpful typedefs.

```
typedef ACE_Svc_Tuple<SVC_HANDLER> AST;
```

```
    typedef ACE_Map_Manager<ACE_HANDLE, ACE_Svc_Tuple<SVC_HANDLER> *, ACE_SYNCH_RW_MUTEX> MAP_MANAGER;

```

```
    typedef ACE_Map_Iterator<ACE_HANDLE, ACE_Svc_Tuple<SVC_HANDLER> *, ACE_SYNCH_RW_MUTEX> MAP_ITERATOR;

```

```
    typedef ACE_Map_Entry<ACE_HANDLE, ACE_Svc_Tuple<SVC_HANDLER> *> MAP_ENTRY;

```

## The following two methods define the Connector's strategies for

creating, connecting, and activating SVC\_HANDLER's, respectively.

```
virtual int make_svc_handler (SVC_HANDLER *&sh);
```

Bridge method for creating a SVC\_HANDLER.  The default is to create a new SVC\_HANDLER only if sh == 0, else sh is unchanged.  However, subclasses can override this policy to perform SVC\_HANDLER creation in any way that they like (such as creating subclass instances of SVC\_HANDLER, using a singleton, dynamically linking the handler, etc.).  Returns -1 if failure, else 0.

```
virtual int connect_svc_handler (
    SVC_HANDLER *&svc_handler,
    const ACE_PEER_CONNECTOR_ADDR &remote_addr,
    ACE_Time_Value *timeout,
    const ACE_PEER_CONNECTOR_ADDR &local_addr,
    int reuse_addr,
    int flags,
    int perms
    );
```

```
virtual int connect_svc_handler (
    SVC_HANDLER *&svc_handler,
    SVC_HANDLER *&sh_copy,
    const ACE_PEER_CONNECTOR_ADDR &remote_addr,
    ACE_Time_Value *timeout,
    const ACE_PEER_CONNECTOR_ADDR &local_addr,
    int reuse_addr,
    int flags,
    int perms
    );
```

Bridge method for connecting the svc\_handler to the remote\_addr.  The default behavior delegates to the PEER\_CONNECTOR::connect.

```
virtual int activate_svc_handler (SVC_HANDLER *svc_handler);
```

Bridge method for activating a svc\_handler with the appropriate concurrency strategy.  The default behavior of this method is to activate the SVC\_HANDLER by calling its open method (which allows the SVC\_HANDLER to define its own concurrency strategy). However, subclasses can override this strategy to do more sophisticated concurrency activations (such as creating the SVC\_HANDLER as an "active object" via multi-threading or multi-processing).

```
virtual int handle_input (ACE_HANDLE);
```

Called by ACE\_Reactor when asynchronous connections fail.

```
virtual int handle_output (ACE_HANDLE);
```

Called by ACE\_Reactor when asynchronous connections succeed.

```
virtual int handle_exception (ACE_HANDLE fd = ACE_INVALID_HANDLE);
```

Called by ACE\_Reactor when asynchronous connections complete (on some platforms only).

## Dynamic linking hooks.

```
virtual int init (int argc, ASYS_TCHAR *argv[]);
```

Default version does no work and returns -1.  Must be overloaded by application developer to do anything meaningful.

```
virtual int fini (void);
```

Calls handle\_close to shutdown the Connector gracefully.

```
virtual int info (ASYS_TCHAR **, size_t) const;
```

Default version returns address info in buf.

## Demultiplexing hooks.

```
virtual int handle_close (
    ACE_HANDLE = ACE_INVALID_HANDLE,
    ACE_Reactor_Mask = ACE_Event_Handler::ALL_EVENTS_MASK
    );
```

Terminate the Client ACE\_Connector by iterating over any unconnected ACE\_Svc\_Handler's and removing them from the ACE\_Reactor.

```
virtual int handle_timeout (
    const ACE_Time_Value &tv,
    const void *arg
    );
```

This method is called if a connection times out before completing.

## Service management hooks.

```
virtual int suspend (void);
```

Default version does no work and returns -1.  Must be overloaded by application developer to do anything meaningful.

```
virtual int resume (void);
```

Default version does no work and returns -1.  Must be overloaded by application developer to do anything meaningful.

```
int create_AST (SVC_HANDLER *, const ACE_Synch_Options &);
```

Creates and inserts an ACE\_Svc\_Tuple into the handler\_map\_. so that we can continue accepting this connection asynchronously.

```
int cleanup_AST (ACE_HANDLE, AST *&);
```

Cleanup the handler\_map\_ and returns the appropriate ACE\_Svc\_Tuple (which is 0 if there is no associated tuple).

```
virtual int connect_i (
    SVC_HANDLER *&svc_handler,
    SVC_HANDLER **sh_copy,
    const ACE_PEER_CONNECTOR_ADDR &remote_addr,
    const ACE_Synch_Options &synch_options,
    const ACE_PEER_CONNECTOR_ADDR &local_addr,
    int reuse_addr,
    int flags,
    int perms
    );
```

Implementation the connect methods.

```
MAP_MANAGER handler_map_;
```

Lookup table that maps an I/O handle to a SVC\_HANDLER \*.

## AUTHOR

Doug Schmidt

## LIBRARY

ace