## NAME

ACE_Svc_Handler - Defines the interface for a service that exchanges data with its connected peer.

## SYNOPSIS

    #include <ace/Svc_Handler.h>

    template<ACE_PEER_STREAM_1, ACE_SYNCH_DECL>
    class ACE_Svc_Handler : public ACE_Task<ACE_SYNCH_USE>
    {
      public:
        ACE_Svc_Handler (
            ACE_Thread_Manager *thr_mgr = 0,
            ACE_Message_Queue<ACE_SYNCH_USE> *mq = 0,
            ACE_Reactor *reactor = ACE_Reactor::instance ()
            );
        virtual ~ACE_Svc_Handler (void);
        virtual int open (void * = 0);
        virtual int close (u_long flags = 0);
        virtual int idle (u_long flags = 0);
        virtual ACE_Recyclable_State recycle_state (void) const;
        virtual int recycle_state (ACE_Recyclable_State new_state);
        virtual void cleanup_hint (void);
        virtual int init (int argc, ASYS_TCHAR *argv[]);
        virtual int fini (void);
        virtual int info (ASYS_TCHAR **info_string, size_t length) 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 &time,
            const void *
            );
        virtual ACE_HANDLE get_handle (void) const;
        virtual void set_handle (ACE_HANDLE);
        ACE_PEER_STREAM &peer (void) const;
        void *operator new (size_t n);
        virtual void destroy (void);
        void operator delete (void *);
        void shutdown (void);
        void dump (void) const;
        virtual void recycler (
            ACE_Connection_Recycling_Strategy *recycler,
            const void *recycling_act
            );
        virtual ACE_Connection_Recycling_Strategy *recycler (void) const;
        virtual const void *recycling_act (void) const;
        virtual int recycle (void * = 0);
      protected:
        ACE_PEER_STREAM peer_;
        int dynamic_;
        char closing_;
        ACE_Connection_Recycling_Strategy *recycler_;
        const void *recycling_act_;
    };

## DESCRIPTION

This class provides a well-defined interface that the Acceptor and Connector pattern factories use as their target. Typically, client applications will subclass ACE_Svc_Handler and do all the interesting work in the subclass. One thing that the ACE_Svc_Handler does contain is a PEER_STREAM endpoint that is initialized by an ACE_Acceptor or ACE_Connector when a connection is established successfully. This endpoint is used to exchange data between a ACE_Svc_Handler and the peer it is connected with.

## Initialization and termination methods.

    ACE_Svc_Handler (
        ACE_Thread_Manager *thr_mgr = 0,
        ACE_Message_Queue<ACE_SYNCH_USE> *mq = 0,
        ACE_Reactor *reactor = ACE_Reactor::instance ()
        );

Constructor initializes the `thr_mgr` and `mq` by passing them down to the `ACE_Task` base class. The `reactor` is passed to the `ACE_Event_Handler`.

    virtual ~ACE_Svc_Handler (void);

Destructor.

    virtual int open (void * = 0);

Activate the client handler. This is typically called by the `ACE_Acceptor` or `ACE_Connector`.

    virtual int close (u_long flags = 0);

Object termination hook -- application-specific cleanup code goes here.

    virtual int idle (u_long flags = 0);

Call this method if you want to recycling the `Svc_Handler` instead of closing it. If the object does not have a recycler, it will be closed.

    virtual ACE_Recyclable_State recycle_state (void) const;

    virtual int recycle_state (ACE_Recyclable_State new_state);

Call this method if you want to get/set the state of the `Svc_Handler`. If the object does not have a recycler, this call will have no effect (and the accessor will return ACE_RECYCLABLE_UNKNOWN).

    virtual void cleanup_hint (void);

When the svc_handle is no longer needed around as a hint, call this method.

## 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);

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

    virtual int info (ASYS_TCHAR **info_string, size_t length) const;

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

## Demultiplexing hooks.

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

Perform termination activities on the SVC_HANDLER. The default behavior is to close down the `peer_` (to avoid descriptor leaks) and to `destroy` this object (to avoid memory leaks)! If you don't want this behavior make sure you override this method...

    virtual int handle_timeout (const ACE_Time_Value &time, const void *);

Default behavior when timeouts occur is to close down the `Svc_Handler` by calling `handle_close`.

    virtual ACE_HANDLE get_handle (void) const;

Get the underlying handle associated with the `peer_`.

    virtual void set_handle (ACE_HANDLE);

Set the underlying handle associated with the `peer_`.

    ACE_PEER_STREAM &peer (void) const;

Returns the underlying PEER_STREAM. Used by `ACE_Acceptor::accept` and `ACE_Connector::connect` factories

    void *operator new (size_t n);

Overloaded new operator. This method unobtrusively records if a `Svc_Handler` is allocated dynamically.

    virtual void destroy (void);

Call this to free up dynamically allocated `Svc_Handlers` (otherwise you will get memory leaks). In general, you should call this method rather than `delete` since this method knows whether or not the object was allocated dynamically, and can act accordingly (i.e., deleting it if it was allocated dynamically).

    void operator delete (void *);

This really should be private so that users are forced to call `destroy`. Unfortunately, the C++ standard doesn't allow there to be a public new and a private delete. It is a bad idea to call this method directly, so use `destroy` instead, unless you know for sure that you've allocated the object dynamically.

    void shutdown (void);

Close down the descriptor and unregister from the Reactor

    void dump (void) const;

Dump the state of an object.

## The following methods are not suppose to be public.

Because friendship is *not* inherited in C++, these methods have to be public.

## Accessors to set/get the connection recycler.

    virtual void recycler (
        ACE_Connection_Recycling_Strategy *recycler,
        const void *recycling_act
        );

Set the recycler and the `recycling_act` that is used during purging and caching.

    virtual ACE_Connection_Recycling_Strategy *recycler (void) const;

Get the recycler.

    virtual const void *recycling_act (void) const;

Get the recycling act.

    virtual int recycle (void * = 0);

Upcall made by the recycler when it is about to recycle the connection. This gives the object a chance to prepare itself for recycling. Return 0 if the object is ready for recycling, -1 on failures.

## AUTHOR

Doug Schmidt and Irfan Pyrarli.

## LIBRARY

ace