## NAME

ACE_WFMO_Reactor_Notify - Unblock the `ACE_WFMO_Reactor` from its event loop, passing it an optional `ACE_Event_Handler` to dispatch.

## SYNOPSIS

    #include <ace/WFMO_Reactor.h>

    class ACE_WFMO_Reactor_Notify : public ACE_Reactor_Notify
    {
      public:
        ACE_WFMO_Reactor_Notify (void);
        virtual int open (
            ACE_Reactor_Impl *wfmo_reactor,
            ACE_Timer_Queue *timer_queue,
            int disable_notify = 0
            );
        virtual int close (void);
        ssize_t notify (
            ACE_Event_Handler *event_handler = 0,
            ACE_Reactor_Mask mask = ACE_Event_Handler::EXCEPT_MASK,
            ACE_Time_Value *timeout = 0
            );
        virtual int dispatch_notifications (
            int &number_of_active_handles,
            ACE_Handle_Set &rd_mask
            );
        virtual ACE_HANDLE get_handle (void) const;
        void max_notify_iterations (int);
        int max_notify_iterations (void);
        virtual void dump (void) const;
      private:
        ACE_Timer_Queue *timer_queue_;
        virtual int handle_signal (
            int signum,
            siginfo_t * = 0,
            ucontext_t * = 0
            );
        ACE_Auto_Event wakeup_one_thread_;
        ACE_Message_Queue<ACE_MT_SYNCH> message_queue_;
        int max_notify_iterations_;
    };

## DESCRIPTION

This implementation is necessary for cases where the `ACE_WFMO_Reactor` is run in a multi-threaded program. In this case, we need to be able to unblock WaitForMultipleObjects() when updates occur other than in the main `ACE_WFMO_Reactor` thread. To do this, we signal an auto-reset event the `ACE_WFMO_Reactor` is listening on. If an `ACE_Event_Handler` and `ACE_Reactor_Mask` is passed to `notify`, the appropriate `handle_*` method is dispatched.

## PUBLIC MEMBERS

    ACE_WFMO_Reactor_Notify (void);

Constructor

    virtual int open (
        ACE_Reactor_Impl *wfmo_reactor,
        ACE_Timer_Queue *timer_queue,
        int disable_notify = 0
        );

Initialization. `timer_queue` is stored to call `gettimeofday`.

    virtual int close (void);

No-op.

    ssize_t notify (
        ACE_Event_Handler *event_handler = 0,
        ACE_Reactor_Mask mask = ACE_Event_Handler::EXCEPT_MASK,
        ACE_Time_Value *timeout = 0
        );

Special trick to unblock `WaitForMultipleObjects` when updates occur. All we do is enqueue `event_handler` and `mask` onto the `ACE_Message_Queue` and wakeup the `WFMO_Reactor` by signaling its `ACE_Event` handle. The `ACE_Time_Value` indicates how long to blocking trying to notify the `WFMO_Reactor`. If `timeout` == 0, the caller will block until action is possible, else will wait until the relative time specified in `timeout` elapses).

    virtual int dispatch_notifications (
        int &number_of_active_handles,
        ACE_Handle_Set &rd_mask
        );

No-op.

    virtual ACE_HANDLE get_handle (void) const;

Returns a handle to the `ACE_Auto_Event`.

    void max_notify_iterations (int);

Set the maximum number of times that the `ACE_WFMO_Reactor_Notify::handle_input` method will iterate and dispatch the `ACE_Event_Handlers` that are passed in via the notify queue before breaking out of its `ACE_Message_Queue::dequeue` loop. By default, this is set to -1, which means "iterate until the queue is empty." Setting this to a value like "1 or 2" will increase "fairness" (and thus prevent starvation) at the expense of slightly higher dispatching overhead.

    int max_notify_iterations (void);

Get the maximum number of times that the `ACE_WFMO_Reactor_Notify::handle_input` method will iterate and dispatch the `ACE_Event_Handlers` that are passed in via the notify queue before breaking out of its `ACE_Message_Queue::dequeue` loop.

    virtual void dump (void) const;

Dump the state of an object.

## PRIVATE MEMBERS

    ACE_Timer_Queue *timer_queue_;

Pointer to the wfmo_reactor's timer queue.

    virtual int handle_signal (
        int signum,
        siginfo_t * = 0,
        ucontext_t * = 0
        );

Called when the notification event waited on by `ACE_WFMO_Reactor` is signaled. This dequeues all pending `ACE_Event_Handlers` and dispatches them.

    ACE_Auto_Event wakeup_one_thread_;

An auto event is used so that we can `signal` it to wakeup one thread up (e.g., when the `notify` method is called).

    ACE_Message_Queue<ACE_MT_SYNCH> message_queue_;

    int max_notify_iterations_;

Keeps track of the maximum number of times that the `ACE_WFMO_Reactor_Notify::handle_input` method will iterate and dispatch the `ACE_Event_Handlers` that are passed in via the notify queue before breaking out of its `ACE_Message_Queue::dequeue` loop. By default, this is set to -1, which means "iterate until the queue is empty."

## AUTHOR

Irfan Pyarali, Tim Harrison, and Doug Schmidt

## LIBRARY

ace