--- name: "ACE_Svc_Handler" 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_Svc_Handler" --- # ACE\_Svc\_Handler(3) Defines the interface for a service that exchanges data with its connected peer. ## NAME ACE\_Svc\_Handler - Defines the interface for a service that exchanges data with its connected peer. ## SYNOPSIS ``` #include template class ACE_Svc_Handler : public ACE_Task { public: ACE_Svc_Handler ( ACE_Thread_Manager *thr_mgr = 0, ACE_Message_Queue *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 *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