## NAME

ACE_Proactor - A manager for asynchronous event demultiplexing.

## SYNOPSIS

    #include <ace/Proactor.h>

    class ACE_Proactor
    {
      public:
        friend class ACE_Proactor_Timer_Handler;
            typedef ACE_Timer_Queue_T<ACE_Handler *, ACE_Proactor_Handle_Timeout_Upcall, ACE_SYNCH_RECURSIVE_MUTEX> TIMER_QUEUE;

        ACE_Proactor (
            ACE_Proactor_Impl *implementation = 0,
            int delete_implementation = 0,
            TIMER_QUEUE *tq = 0
            );
        virtual ~ACE_Proactor (void);
        static ACE_Proactor *instance (size_t threads = 0);
        static ACE_Proactor *instance (ACE_Proactor *);
        static void close_singleton (void);
        static int run_event_loop (void);
        static int run_event_loop (ACE_Time_Value &tv);
        static int end_event_loop (void);
        static int event_loop_done (void);
        virtual int close (void);
        virtual int register_handle (
            ACE_HANDLE handle,
            const void *completion_key
            );
        virtual long schedule_timer (
            ACE_Handler &handler,
            const void *act,
            const ACE_Time_Value &time
            );
        virtual long schedule_repeating_timer (
            ACE_Handler &handler,
            const void *act,
            const ACE_Time_Value &interval
            );
        virtual long schedule_timer (
            ACE_Handler &handler,
            const void *act,
            const ACE_Time_Value &time,
            const ACE_Time_Value &interval
            );
        virtual int cancel_timer (
            ACE_Handler &handler,
            int dont_call_handle_close = 1
            );
        virtual int cancel_timer (
            long timer_id,
            const void **act = 0,
            int dont_call_handle_close = 1
            );
        virtual int handle_events (ACE_Time_Value &wait_time);
        virtual int handle_events (void);
        int wake_up_dispatch_threads (void);
        int close_dispatch_threads (int wait);
        size_t number_of_threads (void) const;
        void number_of_threads (size_t threads);
        TIMER_QUEUE *timer_queue (void) const;
        void timer_queue (TIMER_QUEUE *timer_queue);
        virtual ACE_HANDLE get_handle (void) const;
        virtual ACE_Proactor_Impl *implementation (void) const;
        = Factory methods for the operations virtual ACE_Asynch_Read_Stream_Impl *create_asynch_read_stream (
            void
            );
        virtual ACE_Asynch_Write_Stream_Impl *create_asynch_write_stream (
            void
            );
        virtual ACE_Asynch_Read_File_Impl *create_asynch_read_file (void);
        virtual ACE_Asynch_Write_File_Impl *create_asynch_write_file (
            void
            );
        virtual ACE_Asynch_Accept_Impl *create_asynch_accept (void);
        virtual ACE_Asynch_Transmit_File_Impl *create_asynch_transmit_file (
            void
            );
        = Factory methods for the results virtual ACE_Asynch_Read_Stream_Result_Impl *create_asynch_read_stream_result (
            ACE_Handler &handler,
            ACE_HANDLE handle,
            ACE_Message_Block &message_block,
            u_long bytes_to_read,
            const void* act,
            ACE_HANDLE event = ACE_INVALID_HANDLE,
            int priority = 0,
            int signal_number = ACE_SIGRTMIN
            );
        virtual ACE_Asynch_Write_Stream_Result_Impl *create_asynch_write_stream_result (
            ACE_Handler &handler,
            ACE_HANDLE handle,
            ACE_Message_Block &message_block,
            u_long bytes_to_write,
            const void* act,
            ACE_HANDLE event = ACE_INVALID_HANDLE,
            int priority = 0,
            int signal_number = ACE_SIGRTMIN
            );
        virtual ACE_Asynch_Read_File_Result_Impl *create_asynch_read_file_result (
            ACE_Handler &handler,
            ACE_HANDLE handle,
            ACE_Message_Block &message_block,
            u_long bytes_to_read,
            const void* act,
            u_long offset,
            u_long offset_high,
            ACE_HANDLE event = ACE_INVALID_HANDLE,
            int priority = 0,
            int signal_number = ACE_SIGRTMIN
            );
        virtual ACE_Asynch_Write_File_Result_Impl *create_asynch_write_file_result (
            ACE_Handler &handler,
            ACE_HANDLE handle,
            ACE_Message_Block &message_block,
            u_long bytes_to_write,
            const void* act,
            u_long offset,
            u_long offset_high,
            ACE_HANDLE event = ACE_INVALID_HANDLE,
            int priority = 0,
            int signal_number = ACE_SIGRTMIN
            );
        virtual ACE_Asynch_Accept_Result_Impl *create_asynch_accept_result (
            ACE_Handler &handler,
            ACE_HANDLE listen_handle,
            ACE_HANDLE accept_handle,
            ACE_Message_Block &message_block,
            u_long bytes_to_read,
            const void* act,
            ACE_HANDLE event = ACE_INVALID_HANDLE,
            int priority = 0,
            int signal_number = ACE_SIGRTMIN
            );
        virtual ACE_Asynch_Transmit_File_Result_Impl *create_asynch_transmit_file_result (
            ACE_Handler &handler,
            ACE_HANDLE socket,
            ACE_HANDLE file,
            ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer,
            u_long bytes_to_write,
            u_long offset,
            u_long offset_high,
            u_long bytes_per_send,
            u_long flags,
            const void *act,
            ACE_HANDLE event = ACE_INVALID_HANDLE,
            int priority = 0,
            int signal_number = ACE_SIGRTMIN
            );
        virtual ACE_Asynch_Result_Impl *create_asynch_timer (
            ACE_Handler &handler,
            const void *act,
            const ACE_Time_Value &tv,
            ACE_HANDLE event = ACE_INVALID_HANDLE,
            int priority = 0,
            int signal_number = ACE_SIGRTMIN
            );
        inline ACE_Proactor (size_t = 0, Timer_Queue * = 0);
        static ACE_Proactor *instance (size_t threads = 0);
        static ACE_Proactor *instance (ACE_Proactor *);
        static void close_singleton (void);
        static int run_event_loop (void);
        static int run_event_loop (ACE_Time_Value &tv);
        static int end_event_loop (void);
        static sig_atomic_t event_loop_done (void);
      protected:
        static int post_wakeup_completions (int how_many);
        virtual void implementation (ACE_Proactor_Impl *implementation);
        ACE_Proactor_Impl *implementation_;
        int delete_implementation_;
        static ACE_Proactor *proactor_;
        static int delete_proactor_;
        ACE_Proactor_Timer_Handler *timer_handler_;
        ACE_Thread_Manager thr_mgr_;
        TIMER_QUEUE *timer_queue_;
        int delete_timer_queue_;
        static sig_atomic_t end_event_loop_;
        static sig_atomic_t event_loop_thread_count_;
      private:
        ACE_Proactor (const ACE_Proactor &);
        ACE_Proactor &operator= (const ACE_Proactor &);
    };

## DESCRIPTION

See the Proactor pattern description at http://www.cs.wustl.edu/~schmidt/proactor.ps.gz for more details.

## Proactor event loop management methods.

    static int run_event_loop (void);

Run the event loop until the `ACE_Proactor::handle_events` method returns -1 or the `end_event_loop` method is invoked.

    static int run_event_loop (ACE_Time_Value &tv);

Run the event loop until the `ACE_Proactor::handle_events` method returns -1, the `end_event_loop` method is invoked, or the `ACE_Time_Value` expires.

    static int end_event_loop (void);

Instruct the `ACE_Proactor::instance` to terminate its event loop. This method wakes up all the threads blocked on waiting for completions and end the event loop.

    static int event_loop_done (void);

Report if the `ACE_Proactor::instance` event loop is finished.

    virtual int close (void);

Close the IO completion port.

    virtual int register_handle (
        ACE_HANDLE handle,
        const void *completion_key
        );

This method adds the `handle` to the I/O completion port. This function is a no-op function for Unix systems and returns 0;

## Timer management.

    virtual long schedule_timer (
        ACE_Handler &handler,
        const void *act,
        const ACE_Time_Value &time
        );

Schedule a `handler` that will expire after `time`. If it expires then `act` is passed in as the value to the `handler`'s `handle_timeout` callback method. This method returns a `timer_id`. This `timer_id` can be used to cancel a timer before it expires. The cancellation ensures that `timer_ids` are unique up to values of greater than 2 billion timers. As long as timers don't stay around longer than this there should be no problems with accidentally deleting the wrong timer. Returns -1 on failure (which is guaranteed never to be a valid `timer_id`).

    virtual long schedule_repeating_timer (
        ACE_Handler &handler,
        const void *act,
        const ACE_Time_Value &interval
        );

Same as above except `interval` it is used to reschedule the `handler` automatically.

    virtual long schedule_timer (
        ACE_Handler &handler,
        const void *act,
        const ACE_Time_Value &time,
        const ACE_Time_Value &interval
        );

This combines the above two methods into one. Mostly for backward compatibility.

    virtual int cancel_timer (
        ACE_Handler &handler,
        int dont_call_handle_close = 1
        );

Cancel all timers associated with this `handler`. Returns number of timers cancelled.

    virtual int cancel_timer (
        long timer_id,
        const void **act = 0,
        int dont_call_handle_close = 1
        );

Cancel the single `ACE_Handler` that matches the `timer_id` value (which was returned from the `schedule` method). If `act` is non-NULL then it will be set to point to the ``magic cookie'' argument passed in when the `Handler` was registered. This makes it possible to free up the memory and avoid memory leaks. Returns 1 if cancellation succeeded and 0 if the `timer_id` wasn't found.

    virtual int handle_events (ACE_Time_Value &wait_time);

Dispatch a single set of events. If `wait_time` elapses before any events occur, return 0. Return 1 on success i.e., when a completion is dispatched, non-zero (-1) on errors and errno is set accordingly.

    virtual int handle_events (void);

Block indefinitely until at least one event is dispatched. Dispatch a single set of events. If `wait_time` elapses before any events occur, return 0. Return 1 on success i.e., when a completion is dispatched, non-zero (-1) on errors and errno is set accordingly.

    int wake_up_dispatch_threads (void);

Add wakeup dispatch threads (reinit).

    int close_dispatch_threads (int wait);

Close all dispatch threads.

    size_t number_of_threads (void) const;

    void number_of_threads (size_t threads);

Number of thread used as a parameter to CreatIoCompletionPort.

    TIMER_QUEUE *timer_queue (void) const;

    void timer_queue (TIMER_QUEUE *timer_queue);

Get/Set timer queue.

    virtual ACE_HANDLE get_handle (void) const;

Get the event handle. It is a no-op in POSIX platforms and it returns ACE_INVALID_HANDLE.

    virtual ACE_Proactor_Impl *implementation (void) const;

Get the implementation class.

    = Factory methods for the operations virtual ACE_Asynch_Read_Stream_Impl *create_asynch_read_stream (
        void
        );

Create the correct implementation class for doing Asynch_Read_Stream.

    virtual ACE_Asynch_Write_Stream_Impl *create_asynch_write_stream (
        void
        );

Create the correct implementation class for doing Asynch_Write_Stream.

    virtual ACE_Asynch_Read_File_Impl *create_asynch_read_file (void);

Create the correct implementation class for doing Asynch_Read_File.

    virtual ACE_Asynch_Write_File_Impl *create_asynch_write_file (void);

Create the correct implementation class for doing Asynch_Write_File.

    virtual ACE_Asynch_Accept_Impl *create_asynch_accept (void);

Create the correct implementation class for doing Asynch_Accept.

    virtual ACE_Asynch_Transmit_File_Impl *create_asynch_transmit_file (
        void
        );

Create the correct implementation class for doing Asynch_Transmit_File.

    = Factory methods for the results virtual ACE_Asynch_Read_Stream_Result_Impl *create_asynch_read_stream_result (
        ACE_Handler &handler,
        ACE_HANDLE handle,
        ACE_Message_Block &message_block,
        u_long bytes_to_read,
        const void* act,
        ACE_HANDLE event = ACE_INVALID_HANDLE,
        int priority = 0,
        int signal_number = ACE_SIGRTMIN
        );

Create the correct implementation class for ACE_Asynch_Read_Stream::Result class.

    virtual ACE_Asynch_Write_Stream_Result_Impl *create_asynch_write_stream_result (
        ACE_Handler &handler,
        ACE_HANDLE handle,
        ACE_Message_Block &message_block,
        u_long bytes_to_write,
        const void* act,
        ACE_HANDLE event = ACE_INVALID_HANDLE,
        int priority = 0,
        int signal_number = ACE_SIGRTMIN
        );

Create the correct implementation class for ACE_Asynch_Write_Stream::Result.

    virtual ACE_Asynch_Read_File_Result_Impl *create_asynch_read_file_result (
        ACE_Handler &handler,
        ACE_HANDLE handle,
        ACE_Message_Block &message_block,
        u_long bytes_to_read,
        const void* act,
        u_long offset,
        u_long offset_high,
        ACE_HANDLE event = ACE_INVALID_HANDLE,
        int priority = 0,
        int signal_number = ACE_SIGRTMIN
        );

Create the correct implementation class for ACE_Asynch_Read_File::Result.

    virtual ACE_Asynch_Write_File_Result_Impl *create_asynch_write_file_result (
        ACE_Handler &handler,
        ACE_HANDLE handle,
        ACE_Message_Block &message_block,
        u_long bytes_to_write,
        const void* act,
        u_long offset,
        u_long offset_high,
        ACE_HANDLE event = ACE_INVALID_HANDLE,
        int priority = 0,
        int signal_number = ACE_SIGRTMIN
        );

Create the correct implementation class for ACE_Asynch_Write_File::Result.

    virtual ACE_Asynch_Accept_Result_Impl *create_asynch_accept_result (
        ACE_Handler &handler,
        ACE_HANDLE listen_handle,
        ACE_HANDLE accept_handle,
        ACE_Message_Block &message_block,
        u_long bytes_to_read,
        const void* act,
        ACE_HANDLE event = ACE_INVALID_HANDLE,
        int priority = 0,
        int signal_number = ACE_SIGRTMIN
        );

Create the correct implementation class for ACE_Asynch_Accept::Result.

    virtual ACE_Asynch_Transmit_File_Result_Impl *create_asynch_transmit_file_result (
        ACE_Handler &handler,
        ACE_HANDLE socket,
        ACE_HANDLE file,
        ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer,
        u_long bytes_to_write,
        u_long offset,
        u_long offset_high,
        u_long bytes_per_send,
        u_long flags,
        const void *act,
        ACE_HANDLE event = ACE_INVALID_HANDLE,
        int priority = 0,
        int signal_number = ACE_SIGRTMIN
        );

Create the correct implementation class for ACE_Asynch_Transmit_File::Result.

    virtual ACE_Asynch_Result_Impl *create_asynch_timer (
        ACE_Handler &handler,
        const void *act,
        const ACE_Time_Value &tv,
        ACE_HANDLE event = ACE_INVALID_HANDLE,
        int priority = 0,
        int signal_number = ACE_SIGRTMIN
        );

Create a timer result object which can be used with the Timer mechanism of the Proactor. If `signal_number` is -1, `POSIX_SIG_Proactor` will create a Timer object with a meaningful signal number, choosing the largest signal number from the signal mask of the Proactor.

## AUTHOR

Irfan Pyarali `irfan@cs.wustl.edu`, Tim Harrison `harrison@cs.wustl.edu` and Alexander Babu Arulanthu `alex@cs.wustl.edu`

## Friendship.

## LIBRARY

ace