---
name: "ACE_Proactor"
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_Proactor"
---

# ACE\_Proactor(3)

A manager for asynchronous event demultiplexing.

## 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;
    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
        );
    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

Note that the user does not have to use or know about these methods.

```
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

Note that the user does not have to use or know about these methods unless they want to "fake" 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