custom_event_handler Class Reference
[ACE Reactor Library]

#include <acestl/reactor/custom_event_handler.hpp>

List of all members.

Detailed Description

This class enhances the ACE Reactor framework by providing custom event notifications for event handlers, with zero interference with existing reactor/handler functionality.

It provides the ability to schedule a custom event with a code, an optional delay, and an optional argument

To use, derive from it as you would from ACE_Event_Handler, and override the handle_custom_event() method, e.g

using acestl::custom_event_handler;

// 1. Our custom event handler class
class MyHandler
  : public custom_event_handler
{
private:
  // 2. This method required by acestl::custom_event_handler
  virtual int handle_custom_event(ACE_Time_Value const& current_time
                              ,   long                  code
                              ,   void*                 arg)
  {
    fprintf(stdout, "Received custom event: %ld, %p\n", code, arg);

    if(300 == code)
    {
      std::string* str = static_cast<std::string*>(arg);

      delete str;
    }

    return 0;
  }
. . .
  // 3. This is one of several methods required by ACE_Event_Handler
  virtual int handle_timeout( const ACE_Time_Value  &current_time
                            , const void            *arg)
  {
    return 0;
  }
};

// 4. A cleanup function to ensure that the custom data associated with
// 300 events is not lost; see step 10.
void cleanup_300_proc(void *param, long code, custom_event_handler::event_id id, void *arg)
{
  assert(300 == code);

  int&          num300sCancelled  = *static_cast<int*>(param);
  std::string*  str               = static_cast<std::string*>(arg);

  ++num300sCancelled;

  delete str;
}


// 5. Create an instance of MyHandler
custom_event_handler* mh = new MyHandler();

// 6. Schedule an event with id 100, testing the return to ensure it's
// been scheduled without error
if(NULL == mh->schedule_custom_event(100))
{
  std::err << "Failed to scheduled event (code=100)!" << std::endl;
}
else
{
  // It's been scheduled ok
  //
  // This assert simply enforces what we know: that there is 1 or more
  // (1 in this case) pending events whose event code is 100
  //
  // Note: we can only assert this here because we have not yet
  // started the reactor event loop; see step 11.
  assert(mh->has_custom_events(100));
}

// 7. Schedule an event with id 200 to be dispatched in 10 seconds
custom_event_handler::event_id  id200 = mh->schedule_custom_event(200, ACE_Time_Value(10));

// 8. Schedule an event with id 300 to be dispatched in 20 seconds, with
// a custom argument (an instance of std::string)
mh->schedule_custom_event(300, ACE_Time_Value(20), new std::string("300"));

// 9. Cancel the 200 event
//
// Note: you can only cancel a single event via its unique event id.
mh->cancel_custom_event(id200);

// 10. Cancel all 300 events
//
// Remarks: this has to use a cancel handler to 'release' the resource
// associated with the custom argument. If this is not done, then
// the std::string instance would not be destroyed, and we'd have a
// memory leak
//
// Note: Cancelling via an event code cancels *all* pending events with
// that code.
int num300sCancelled = 0;

mh->cancel_custom_events(300, cleanup_300_proc, &num300sCancelled);

assert(1 == num300sCancelled); // Again, this is only valid because event loop not yet started

// 11. Start the reactor loop. Events will be dispatched from here on in
ACE_Reactor::instance()->run_reactor_event_loop();

Public Types

Types
typedef ACE_Event_Handler parent_class_type
typedef custom_event_handler class_type
typedef bool bool_type
typedef event_id_ * event_id
 An opaque type that identifies pending event instances.
typedef void(* cancelled_event_code_fn )(void *param, long code, event_id id, void *arg)
 Type of the callback function that may be passed to custom_event_handler::cancel_custom_events, which will receive information on each cancelled event instance.

Public Member Functions

virtual ~custom_event_handler () throw ()
 Destructor.
virtual int handle_custom_event (ACE_Time_Value const &current_time, long code, void *arg)=0
 This (private) pure virtual function is implemented by derived classes to handle the custom events.
Operations
event_id schedule_custom_event (long code, ACE_Time_Value const &delay, void *arg=0)
 Registers the custom event.
event_id schedule_custom_event (long code, void *arg=0)
 Registers the custom event for immediate action.
int cancel_custom_events (long code)
 Cancels the event(s) corresponding to the given event code.
int cancel_custom_events (long code, cancelled_event_code_fn pfn, void *param)
 Cancels the event(s) corresponding to the given event code, invoking the given callback function with details of each cancelled event.
int cancel_custom_event (event_id event, void **parg=NULL)
 Cancels the given event.
Attributes
int has_custom_events (long code) const
 Indicates whether the event handler has one or more custom events registered for the given code.
int has_custom_event (long code) const
 [DEPRECATED] Analogue of has_custom_events()
int has_custom_event (event_id event) const
 Indicates whether the event handler has the given event registered.

Protected Member Functions

 custom_event_handler (ACE_Reactor *reactor=ACE_Reactor::instance(), int priority=ACE_Event_Handler::LO_PRIORITY)
 This protected constructor is used to pass initialisation parameters throught to the parent (ACE_Event_Handler) class from the concrete handler class.

Classes

class  callback_hook
struct  event_id_
struct  event_info

Member Typedef Documentation

typedef event_id_* event_id

An opaque type that identifies pending event instances.

The only well-known value is NULL, which indicates no-event.

typedef void(* cancelled_event_code_fn)(void *param, long code, event_id id, void *arg)

Type of the callback function that may be passed to custom_event_handler::cancel_custom_events, which will receive information on each cancelled event instance.

Constructor & Destructor Documentation

custom_event_handler ( ACE_Reactor *  reactor = ACE_Reactor::instance(),
int  priority = ACE_Event_Handler::LO_PRIORITY 
) [explicit, protected]

This protected constructor is used to pass initialisation parameters throught to the parent (ACE_Event_Handler) class from the concrete handler class.

Parameters:
reactor The reactor instance with which this event-handler will interact
priority The priority for this handler
Exceptions:
- Does not throw an exception

virtual ~custom_event_handler (  )  throw () [virtual]

Destructor.

Member Function Documentation

event_id schedule_custom_event ( long  code,
ACE_Time_Value const &  delay,
void *  arg = 0 
)

Registers the custom event.

Parameters:
code The event code that identifies the event for this event handler instance, and will be passed back to the handle_custom_event() callback
delay The interval after which the event callback will be operable
arg An optional event parameter, which will be passed back to the handle_custom_event() callback
Returns:
NULL on failure, the event id on success
Remarks:
The custom event can be cancelled via cancel_custom_event()
Note:
Custom events are "one-shot". When the event delay elapses and the handle_custom_event() callback is called, the event has been deregistered from this handler. There is no need to call cancel_custom_event(), and doing so is semantically wrong, though it has no effect.

event_id schedule_custom_event ( long  code,
void *  arg = 0 
)

Registers the custom event for immediate action.

Parameters:
code The event code that identifies the event for this event handler instance, and will be passed back to the handle_custom_event() callback
arg An optional event parameter, which will be passed back to the handle_custom_event() callback
Returns:
NULL on failure, the event id on success
Remarks:
The custom event can be cancelled via cancel_custom_event()
Note:
Custom events are "one-shot". When the event delay elapses and the handle_custom_event() callback is called, the event has been deregistered from this handler. There is no need to call cancel_custom_event(), and doing so is semantically wrong, though it has no effect.

int cancel_custom_events ( long  code  ) 

Cancels the event(s) corresponding to the given event code.

Parameters:
code The code of the event(s) to be cancelled
Returns:
-1 on failure, 0 on success
Note:
There is no need to call this function if the event handler callback handle_custom_event() has been called, since the event is already deregistered at that point.

int cancel_custom_events ( long  code,
cancelled_event_code_fn  pfn,
void *  param 
)

Cancels the event(s) corresponding to the given event code, invoking the given callback function with details of each cancelled event.

Parameters:
code The code of the event(s) to be cancelled
pfn Pointer to a function that will be called for each cancelled event
param A caller-supplied parameter that will be passed back to the callback function
Returns:
-1 on failure, 0 on success
It is used as shown in the following example: 
  class MyHandler
    : public custom_event_handler
  {
    . . .
  };

  void cancel_proc(void *param, long code, custom_event_handler::event_id id, void *arg)
  {
    ++*static_cast<int*>(arg);
  }

  MyHandler*  mh = new MyHandler(. . .);
  int         cancelCount = 0;

  id = mh->schedule_custom_event(100, NULL);

  . . .

  // cancel_proc() will be invoked for all events having event code 100 that
  // have not yet been dispatched or cancelled at the time of execution of
  // this method
  mh->cancel_custom_events(100, cancel_proc, &cancelCount);

int cancel_custom_event ( event_id  event,
void **  parg = NULL 
)

Cancels the given event.

Parameters:
event The event to be cancelled
parg Optional pointer to a variable to receive the argument specified when the event was scheduled
Returns:
-1 on failure, 0 on success
Note:
There is no need to call this function if the event handler callback handle_custom_event() has been called, since the event is already deregistered at that point.

int has_custom_events ( long  code  )  const

Indicates whether the event handler has one or more custom events registered for the given code.

Parameters:
code The custom event code
Return values:
0 if no events are registered for the given code
1 if one or more events are registered for the hiven code

int has_custom_event ( long  code  )  const

[DEPRECATED] Analogue of has_custom_events()

Deprecated:
This method is deprecated in favour of has_custom_events()

int has_custom_event ( event_id  event  )  const

Indicates whether the event handler has the given event registered.

Parameters:
event The event id
Return values:
0 if the event id matches an outstanding event instance
1 if the event id does not match an outstanding event instance

virtual int handle_custom_event ( ACE_Time_Value const &  current_time,
long  code,
void *  arg 
) [pure virtual]

This (private) pure virtual function is implemented by derived classes to handle the custom events.

Parameters:
current_time The time at which the event was dispatched by the reactor
code The event code
arg The argument specified to schedule_custom_event()

The documentation for this class was generated from the following file:
Generated on Thu Jun 10 08:58:23 2010 for STLSoft by  doxygen 1.5.6