## NAME

ACE_Acceptor - Abstract factory for creating a service handler (SVC_HANDLER), accepting into the SVC_HANDLER, and activating the SVC_HANDLER.

## SYNOPSIS

    #include <ace/Acceptor.h>

    template<class SVC_HANDLER, ACE_PEER_ACCEPTOR_1>
    class ACE_Acceptor : public ACE_Service_Object
    {
      public:
        ACE_Acceptor (ACE_Reactor * = 0, int use_select = 1);
        ACE_Acceptor (
            const ACE_PEER_ACCEPTOR_ADDR &local_addr,
            ACE_Reactor * = ACE_Reactor::instance (),
            int flags = 0,
            int use_select = 1,
            int reuse_addr = 1
            );
        int open (
            const ACE_PEER_ACCEPTOR_ADDR &,
            ACE_Reactor * = ACE_Reactor::instance (),
            int flags = 0,
            int use_select = 1,
            int reuse_addr = 1
            );
        virtual ~ACE_Acceptor (void);
        virtual operator ACE_PEER_ACCEPTOR &() const;
        virtual ACE_PEER_ACCEPTOR &acceptor (void) const;
        virtual ACE_HANDLE get_handle (void) const;
        virtual int close (void);
        void dump (void) const;
        ACE_ALLOC_HOOK_DECLARE;
      protected:
        virtual int make_svc_handler (SVC_HANDLER *&sh);
        virtual int accept_svc_handler (SVC_HANDLER *svc_handler);
        virtual int activate_svc_handler (SVC_HANDLER *svc_handler);
        virtual int handle_close (
            ACE_HANDLE = ACE_INVALID_HANDLE,
            ACE_Reactor_Mask = ACE_Event_Handler::ALL_EVENTS_MASK
            );
        virtual int handle_input (ACE_HANDLE);
        virtual int init (int argc, ASYS_TCHAR *argv[]);
        virtual int fini (void);
        virtual int info (ASYS_TCHAR **buf, size_t) const;
        virtual int suspend (void);
        virtual int resume (void);
        ACE_PEER_ACCEPTOR peer_acceptor_;
        int flags_;
        int use_select_;
    };

## DESCRIPTION

Implements the basic strategy for passively establishing connections with clients. An ACE_Acceptor is parameterized by concrete types that conform to the interfaces of PEER_ACCEPTOR and SVC_HANDLER. The PEER_ACCEPTOR 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_Acceptor inherits from ACE_Service_Object, which in turn inherits from ACE_Event_Handler. This enables the ACE_Reactor to dispatch the ACE_Acceptor's handle_input method when connection events occur. The handle_input method performs the ACE_Acceptor's default creation, connection establishment, and service activation strategies. These strategies can be overridden by subclasses individually or as a group.

## Initialization and termination methods.

    ACE_Acceptor (ACE_Reactor * = 0, int use_select = 1);

"Do-nothing" constructor.

    ACE_Acceptor (
        const ACE_PEER_ACCEPTOR_ADDR &local_addr,
        ACE_Reactor * = ACE_Reactor::instance (),
        int flags = 0,
        int use_select = 1,
        int reuse_addr = 1
        );

Initialize and register `this` with the Reactor and listen for connection requests at the designated `local_addr`. `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. If `use_select` is non-zero then `select` is used to determine when to break out of the `accept` loop. `reuse_addr` is passed down to the `PEER_ACCEPTOR`. If it is non-zero this will allow the OS to reuse this listen port.

    int open (
        const ACE_PEER_ACCEPTOR_ADDR &,
        ACE_Reactor * = ACE_Reactor::instance (),
        int flags = 0,
        int use_select = 1,
        int reuse_addr = 1
        );

Initialize and register `this` with the Reactor and listen for connection requests at the designated `local_addr`. `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. If `use_select` is non-zero then `select` is used to determine when to break out of the `accept` loop. `reuse_addr` is passed down to the `PEER_ACCEPTOR`. If it is non-zero this will allow the OS to reuse this listen port.

    virtual ~ACE_Acceptor (void);

Close down the Acceptor's resources.

    virtual operator ACE_PEER_ACCEPTOR &() const;

Return the underlying PEER_ACCEPTOR object.

    virtual ACE_PEER_ACCEPTOR &acceptor (void) const;

Return the underlying PEER_ACCEPTOR object.

    virtual ACE_HANDLE get_handle (void) const;

Returns the listening acceptor's `ACE_HANDLE`.

    virtual int close (void);

Close down the Acceptor

    void dump (void) const;

Dump the state of an object.

    ACE_ALLOC_HOOK_DECLARE;

Declare the dynamic allocation hooks.

## The following three methods define the Acceptor's strategies

for creating, accepting, 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` 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 on failure, else 0.

    virtual int accept_svc_handler (SVC_HANDLER *svc_handler);

Bridge method for accepting the new connection into the `svc_handler`. The default behavior delegates to the PEER_ACCEPTOR::accept.

    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 making the SVC_HANDLER as an "active object" via multi-threading or multi-processing).

## Demultiplexing hooks.

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

Perform termination activities when `this` is removed from the `reactor`.

    virtual int handle_input (ACE_HANDLE);

Accepts all pending connections from clients, and creates and activates SVC_HANDLERs.

## 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`.

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

Default version returns address info in `buf`.

## Service management hooks.

    virtual int suspend (void);

This method calls `Reactor::suspend`.

    virtual int resume (void);

This method calls `Reactor::resume`.

## AUTHOR

Doug Schmidt

## LIBRARY

ace