NAME
ACE_Event_Handler -
Provides an abstract interface for handling various types of
I/O, timer, and signal events.
SYNOPSIS
#include <ace/Event_Handler.h>
class ACE_Event_Handler
{
public:
enum { LO_PRIORITY = 0, HI_PRIORITY = 10, NULL_MASK = 0, #if defined (
ACE_USE_POLL) READ_MASK = POLLIN,
WRITE_MASK = POLLOUT,
EXCEPT_MASK = POLLPRI,
#else READ_MASK = 0x1,
WRITE_MASK = 0x4,
EXCEPT_MASK = 0x2,
#endif RWE_MASK = READ_MASK | WRITE_MASK | EXCEPT_MASK,
DONT_CALL = 0x100 };
virtual ~ACE_Event_Handler (void);
virtual ACE_HANDLE get_handle (void) const;
virtual void set_handle (ACE_HANDLE);
virtual int get_priority (void) const;
virtual void set_priority (int priority);
virtual int handle_input (ACE_HANDLE fd = ACE_INVALID_HANDLE);
virtual int handle_output (ACE_HANDLE fd = ACE_INVALID_HANDLE);
virtual int handle_exception (ACE_HANDLE fd = ACE_INVALID_HANDLE);
virtual int handle_timeout (
const ACE_Time_Value &tv,
const void *arg = 0
);
virtual int handle_close (
ACE_HANDLE fd,
ACE_Reactor_Mask close_mask
);
virtual int handle_signal (
int signum,
siginfo_t * = 0,
ucontext_t * = 0
);
virtual int handle_input_complete (
ACE_Message_Block *message,
long bytes_transferred
);
virtual int handle_output_complete (
ACE_Message_Block *message,
long bytes_transferred
);
virtual ACE_Message_Block *get_message (void);
protected:
ACE_Event_Handler (void);
int priority_;
};
DESCRIPTION
Derived classes read/write input/output on an I/O
descriptor, handle an exception raised on an I/O
descriptor, handle a timer's expiration, or handle a
signal.
The following methods must be supplied by subclasses in order
to specialize the behavior of an Event_Handler.
virtual ACE_HANDLE get_handle (void) const;
virtual void set_handle (ACE_HANDLE);
Priority runs from MIN_PRIORITY (which is the
lowest"
priority") to MAX_PRIORITY (which is the "highest priority").
virtual int get_priority (void) const;
Get the priority of the Event_Handler.
virtual void set_priority (int priority);
Set the priority of the Event_Handler.
virtual int handle_input (ACE_HANDLE fd = ACE_INVALID_HANDLE);
Called when input events occur (e.g., connection or data).
virtual int handle_output (ACE_HANDLE fd = ACE_INVALID_HANDLE);
Called when output events are possible (e.g., flow control
abates).
virtual int handle_exception (ACE_HANDLE fd = ACE_INVALID_HANDLE);
Called when execption events occur (e.g., SIGURG).
virtual int handle_timeout (
const ACE_Time_Value &tv,
const void *arg = 0
);
Called when timer expires.
virtual int handle_close (ACE_HANDLE fd, ACE_Reactor_Mask close_mask);
Called when object is removed from the ACE_Reactor
virtual int handle_signal (
int signum,
siginfo_t * = 0,
ucontext_t * = 0
);
Called when object is signaled by OS (either via UNIX signals or
when a Win32 object becomes signaled).
Proactor callbacks.
Win32 specific. An Event_Handler can be given to a Proactor
with a {RECV,SEND}_MASK. The Proactor calls back
get_message and get_handle to perform the correct
operations (send/recv). When the send/recv is complete,
handle_{input,output} is called. Thus, Event_Handlers are
used for "proactive I/O" where they are told WHEN THE
OPERATION IS COMPLETE. Alternatively, the _Reactor_ tells
Event_Handlers WHEN THE OPERATION CAN BE PERFORMED.
virtual int handle_input_complete (
ACE_Message_Block *message,
long bytes_transferred
);
Called back by the Proactor when an asynchronous input operation
is complete. If this method returns 0 the Proactor will
initiate another asynchronous receive; if a 0 is returned the
Proactor will not reinitiate a receive; and if a -1 is returned,
then no receive is reinitiated and handle_close is called. If
bytes_transferred = 0, then the I/O operation completed
successfully. If bytes_transferred == -1, then the I/O
operation failed. Check message for total bytes received and
errno for reason.
virtual int handle_output_complete (
ACE_Message_Block *message,
long bytes_transferred
);
Called back by the Proactor when an asynchronous output operation
is complete. If this method returns 0 the Proactor will
initiate another asynchronous send; if a 0 is returned the
Proactor will not reinitiate a send; and if a -1 is returned,
then no send is reinitiated and handle_close is called. If
bytes_transferred = 0, then the I/O operation completed
successfully. If bytes_transferred == -1, then the I/O
operation failed. Check message for total bytes received and
errno for reason.
virtual ACE_Message_Block *get_message (void);
Factory that creates an ACE_Message_Block that is used by the
Proactor to send or receive a message asynchronously. When the
asynchronous call completes, this message is returned to the
IO_Handler with its contents filled in. By default,
get_message dynamically creates a new ACE_Message_Block.
AUTHOR
Doug Schmidt
LIBRARY
ace