Merge pull request #2309 from mitza-oci/warnings
[ACE_TAO.git] / ACE / ace / Reactor.h
blobef61f2e680c5555efd5ab5180428d18081b4efd8
1 // -*- C++ -*-
3 //=============================================================================
4 /**
5 * @file Reactor.h
7 * @author Irfan Pyarali <irfan@cs.wustl.edu>
8 * @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
9 */
10 //=============================================================================
12 #ifndef ACE_REACTOR_H
13 #define ACE_REACTOR_H
15 #include /**/ "ace/pre.h"
17 // Timer Queue is a complicated template class. A simple forward
18 // declaration will not work.
19 #include "ace/Timer_Queuefwd.h"
21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
22 # pragma once
23 #endif /* ACE_LACKS_PRAGMA_ONCE */
25 // Contains the timer related interface for the Reactor.
26 #include "ace/Reactor_Timer_Interface.h"
28 // Event_Handler.h contains the definition of ACE_Reactor_Mask
29 #include "ace/Event_Handler.h"
31 // Get ACE_Time_Value in
32 #include "ace/Time_Value.h"
33 #include "ace/Synch_Traits.h"
35 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
37 class ACE_Reactor_Impl;
38 class ACE_Handle_Set;
39 class ACE_Sig_Action;
40 class ACE_Sig_Handler;
41 class ACE_Sig_Set;
43 /**
44 * @class ACE_Reactor
46 * @brief This class forwards all methods to its delegation/implementation class, e.g.,
47 * ACE_Select_Reactor or ACE_WFMO_Reactor.
49 class ACE_Export ACE_Reactor : public ACE_Reactor_Timer_Interface
51 public:
52 /// Operations on the "ready" mask and the "dispatch" mask.
53 enum
55 /// Retrieve current value of the the "ready" mask or the
56 /// "dispatch" mask.
57 GET_MASK = 1,
58 /// Set value of bits to new mask (changes the entire mask).
59 SET_MASK = 2,
60 /// Bitwise "or" the value into the mask (only changes enabled
61 /// bits).
62 ADD_MASK = 3,
63 /// Bitwise "and" the negation of the value out of the mask (only
64 /// changes enabled bits).
65 CLR_MASK = 4
68 /**
69 * You can specify a hook function to event-handling methods that will
70 * be called after each iteration of event handling. If the hook function
71 * returns a non-zero value, the event loop will immediately resume
72 * waiting for the next event(s) to process without checking the error
73 * status of the just-completed iteration of event handling or the
74 * end-of-loop indication. If the hook function returns 0, the event
75 * handling error status and the end-of-loop indication will be checked
76 * as normal, just as if there is no hook function specified.
78 typedef int (*REACTOR_EVENT_HOOK)(ACE_Reactor *);
80 /// Get pointer to a process-wide ACE_Reactor.
81 static ACE_Reactor *instance ();
83 /**
84 * Set pointer to a process-wide ACE_Reactor and return existing
85 * pointer. If @a delete_reactor == true then we'll delete the Reactor
86 * at destruction time.
88 static ACE_Reactor *instance (ACE_Reactor *, bool delete_reactor = false);
90 /// Delete the dynamically allocated Singleton
91 static void close_singleton ();
93 /// Name of the dll in which the dll lives.
94 static const ACE_TCHAR *dll_name ();
96 /// Name of the component--ACE_Reactor in this case.
97 static const ACE_TCHAR *name ();
99 // = Singleton reactor event loop management methods.
101 // Note that these method ONLY work on the "Singleton Reactor,"
102 // i.e., the one returned from ACE_Reactor::instance().
104 * Run the event loop until the
105 * ACE_Reactor::handle_events()/ACE_Reactor::alertable_handle_events()
106 * method returns -1 or the end_event_loop() method is invoked.
107 * Note that this method can only be used by the singleton
108 * ACE_Reactor::instance(). Thus, to run another reactor use
109 * ACE_Reactor::run_reactor_event_loop().
111 * @deprecated Use ACE_Reactor::instance()->run_reactor_event_loop() instead
113 static int run_event_loop ();
114 static int run_alertable_event_loop ();
117 * Run the event loop until the ACE_Reactor::handle_events() or
118 * <ACE_Reactor::alertable_handle_events> methods returns -1, the
119 * end_event_loop() method is invoked, or the ACE_Time_Value
120 * expires. Note that this method can only be used by the singleton
121 * ACE_Reactor::instance(). Thus, to run another reactor use
122 * <ACE_Reactor::run_reactor_event_loop>.
124 * @deprecated Use ACE_Reactor::instance()->run_reactor_event_loop() instead
126 static int run_event_loop (ACE_Time_Value &tv);
127 static int run_alertable_event_loop (ACE_Time_Value &tv);
130 * Instruct the ACE_Reactor::instance() to terminate its event loop
131 * and notifies the ACE_Reactor::instance() so that it can wake up
132 * and close down gracefully. Note that this method can only be
133 * used by the singleton ACE_Reactor::instance(). Thus, to
134 * terminate another reactor, use
135 * <ACE_Reactor::end_reactor_event_loop>.
137 * @deprecated Use ACE_Reactor::instance()->end_reactor_event_loop() instead
139 static int end_event_loop ();
142 * Report if the ACE_Reactor::instance()'s event loop is finished.
143 * Note that this method can only be used by the singleton
144 * ACE_Reactor::instance(). Thus, to check another reactor use
145 * <ACE_Reactor::reactor_event_loop_done>.
147 * @deprecated Use ACE_Reactor::instance()->reactor_event_loop_done() instead
149 static int event_loop_done ();
152 * Resets the ACE_Reactor::end_event_loop_ static so that the
153 * run_event_loop() method can be restarted. Note that this method
154 * can only be used by the singleton ACE_Reactor::instance(). Thus,
155 * to reset another reactor use ACE_Reactor::reset_reactor_event_loop().
157 * @deprecated Use ACE_Reactor::instance()->reset_reactor_event_loop()
158 * instead
160 static void reset_event_loop ();
163 * The singleton reactor is used by the ACE_Service_Config.
164 * Therefore, we must check for the reconfiguration request and
165 * handle it after handling an event.
167 static int check_reconfiguration (ACE_Reactor *);
169 // = Reactor event loop management methods.
171 // These methods work with an instance of a reactor.
173 * Run the event loop until the ACE_Reactor::handle_events() or
174 * ACE_Reactor::alertable_handle_events() method returns -1 or
175 * the end_reactor_event_loop() method is invoked.
177 int run_reactor_event_loop (REACTOR_EVENT_HOOK = 0);
178 int run_alertable_reactor_event_loop (REACTOR_EVENT_HOOK = 0);
181 * Run the event loop until the ACE_Reactor::handle_events() or
182 * ACE_Reactor::alertable_handle_events() method returns -1, the
183 * end_reactor_event_loop() method is invoked, or the ACE_Time_Value
184 * expires while the underlying event demultiplexer is waiting for
185 * events.
186 * Note that it is possible for events to continuously be available,
187 * avoiding the need to wait for events. In this situation the timeout
188 * value will not have an opportunity to expire until the next time
189 * the underlying event demultiplexer waits for events.
191 int run_reactor_event_loop (ACE_Time_Value &tv,
192 REACTOR_EVENT_HOOK = 0);
193 int run_alertable_reactor_event_loop (ACE_Time_Value &tv,
194 REACTOR_EVENT_HOOK = 0);
197 * Instruct the Reactor to terminate its event loop and notifies the
198 * Reactor so that it can wake up and deactivate
199 * itself. Deactivating the Reactor would allow the Reactor to be
200 * shutdown gracefully. Internally the Reactor calls deactivate ()
201 * on the underlying implementation.
202 * Any queued notifications remain queued on return from this method.
203 * If the event loop is restarted in the future, the notifications
204 * will be dispatched then. If the reactor is closed or deleted without
205 * further dispatching, the notifications will be lost.
207 int end_reactor_event_loop ();
209 /// Indicate if the Reactor's event loop has been ended.
210 int reactor_event_loop_done ();
212 /// Resets the ACE_Reactor::end_event_loop_ static so that the
213 /// run_event_loop() method can be restarted.
214 void reset_reactor_event_loop ();
217 * Create the Reactor using @a implementation. The flag
218 * @a delete_implementation tells the Reactor whether or not to
219 * delete the @a implementation on destruction.
221 ACE_Reactor (ACE_Reactor_Impl *implementation = 0,
222 bool delete_implementation = false);
224 /// Close down and release all resources.
226 * Any notifications that remain queued on this reactor instance are
227 * lost.
229 virtual ~ACE_Reactor ();
232 * Initialize the ACE_Reactor to manage @a max_number_of_handles.
233 * If @a restart is false then the ACE_Reactor's handle_events()
234 * method will be restarted automatically when @c EINTR occurs. If
235 * @a signal_handler or @a timer_queue are non-0 they are used as the
236 * signal handler and timer queue, respectively.
238 int open (size_t max_number_of_handles,
239 bool restart = false,
240 ACE_Sig_Handler *signal_handler = 0,
241 ACE_Timer_Queue *timer_queue = 0);
243 /// Use a user specified signal handler instead.
244 int set_sig_handler (ACE_Sig_Handler *signal_handler);
246 /// Set a user-specified timer queue.
247 int timer_queue (ACE_Timer_Queue *tq);
249 /// Return the current ACE_Timer_Queue.
250 ACE_Timer_Queue *timer_queue () const;
252 /// Close down and release all resources.
253 int close ();
255 // = Event loop drivers.
258 * Returns non-zero if there are I/O events "ready" for dispatching,
259 * but does not actually dispatch the event handlers. By default,
260 * don't block while checking this, i.e., "poll".
262 int work_pending (const ACE_Time_Value &max_wait_time = ACE_Time_Value::zero);
265 * This event loop driver blocks for up to @a max_wait_time before
266 * returning. It will return earlier if events occur. Note that
267 * @a max_wait_time can be 0, in which case this method blocks
268 * indefinitely until events occur.
270 * @a max_wait_time is decremented to reflect how much time this call
271 * took. For instance, if a time value of 3 seconds is passed to
272 * handle_events and an event occurs after 2 seconds,
273 * @a max_wait_time will equal 1 second. This can be used if an
274 * application wishes to handle events for some fixed amount of
275 * time.
277 * Returns the total number of timers and I/O ACE_Event_Handlers
278 * that were dispatched, 0 if the @a max_wait_time elapsed without
279 * dispatching any handlers, or -1 if an error occurs.
281 * The only difference between alertable_handle_events() and
282 * handle_events() is that in the alertable case, the eventloop will
283 * return when the system queues an I/O completion routine or an
284 * Asynchronous Procedure Call.
286 int handle_events (ACE_Time_Value *max_wait_time = 0);
287 int alertable_handle_events (ACE_Time_Value *max_wait_time = 0);
290 * This method is just like the one above, except the
291 * @a max_wait_time value is a reference and can therefore never be
292 * NULL.
294 * The only difference between alertable_handle_events() and
295 * handle_events() is that in the alertable case, the eventloop will
296 * return when the system queues an I/O completion routine or an
297 * Asynchronous Procedure Call.
299 int handle_events (ACE_Time_Value &max_wait_time);
300 int alertable_handle_events (ACE_Time_Value &max_wait_time);
302 // = Register and remove handlers.
305 * Register handler for I/O events.
307 * A handler can be associated with multiple handles. A handle
308 * cannot be associated with multiple handlers.
310 * The handle will come from ACE_Event_Handler::get_handle().
312 * Reactor will call ACE_Event_Handler::add_reference() for a new
313 * handler/handle pair.
315 * If this handler/handle pair has already been registered, any new
316 * masks specified will be added. In this case,
317 * ACE_Event_Handler::add_reference() will not be called.
319 * If the registered handler is currently suspended, it will remain
320 * suspended. When the handler is resumed, it will have the
321 * existing masks plus any masks added through this call. Handlers
322 * do not have partial suspensions.
324 int register_handler (ACE_Event_Handler *event_handler,
325 ACE_Reactor_Mask mask);
328 * Register handler for I/O events.
330 * Same as register_handler(ACE_Event_Handler*,ACE_Reactor_Mask),
331 * except handle is explicitly specified.
333 int register_handler (ACE_HANDLE io_handle,
334 ACE_Event_Handler *event_handler,
335 ACE_Reactor_Mask mask);
337 #if defined (ACE_WIN32)
339 * Register handler for OS events.
341 * Register an @a event_handler that will be notified when
342 * <event_handle> is signaled. This will call back its
343 * <handle_signal> hook method.
345 * Reactor will call ACE_Event_Handler::add_reference() for a new
346 * handler/handle pair.
348 * This interface is only available Win32 platforms because
349 * ACE_HANDLE is an int on non-Win32 platforms and compilers are not
350 * able to tell the difference between
351 * register_handler(ACE_Event_Handler*,ACE_Reactor_Mask) and
352 * register_handler(ACE_Event_Handler*,ACE_HANDLE).
354 int register_handler (ACE_Event_Handler *event_handler,
355 ACE_HANDLE event_handle = ACE_INVALID_HANDLE);
356 #endif /* ACE_WIN32 */
359 * Register handler for I/O events.
361 * Similar to
362 * register_handler(ACE_HANDLE,ACE_Event_Handler*,ACE_Reactor_Mask),
363 * except that the user gets to specify the event handle that will
364 * be used for this registration. This only applies to Reactors
365 * that use event handles for I/O registrations.
367 int register_handler (ACE_HANDLE event_handle,
368 ACE_HANDLE io_handle,
369 ACE_Event_Handler *event_handler,
370 ACE_Reactor_Mask mask);
373 * Register handler for multiple I/O events.
375 * Shorthand for calling
376 * register_handler(ACE_HANDLE,ACE_Event_Handler*,ACE_Reactor_Mask),
377 * multiple times for the same @a event_handler and @a masks but
378 * different @a handles.
380 int register_handler (const ACE_Handle_Set &handles,
381 ACE_Event_Handler *event_handler,
382 ACE_Reactor_Mask masks);
385 * Register handler for signals.
387 * Register @a new_sh to handle the signal @a signum using the
388 * @a new_disp. Returns the @a old_sh that was previously registered
389 * (if any), along with the @a old_disp of the signal handler.
391 * Reactor will call ACE_Event_Handler::add_reference() on @a new_sh
392 * and ACE_Event_Handler::remove_reference() on @a old_sh.
394 int register_handler (int signum,
395 ACE_Event_Handler *new_sh,
396 ACE_Sig_Action *new_disp = 0,
397 ACE_Event_Handler **old_sh = 0,
398 ACE_Sig_Action *old_disp = 0);
401 * Register handler for multiple signals.
403 * Shorthand for calling
404 * register_handler(int,ACE_Event_Handler*,ACE_Sig_Action*,ACE_Event_Handler**,ACE_Sig_Action*)
405 * multiple times for the same @a event_handler and @a sig_action but
406 * different <signals>.
408 int register_handler (const ACE_Sig_Set &sigset,
409 ACE_Event_Handler *event_handler,
410 ACE_Sig_Action *sig_action = 0);
413 * Remove @a masks from @a handle registration.
415 * For I/O handles, @a masks are removed from the Reactor. Unless
416 * @a masks includes ACE_Event_Handler::DONT_CALL,
417 * ACE_Event_Handler::handle_close() will be called with the @a masks
418 * that have been removed. If all masks have been removed,
419 * ACE_Event_Handler::remove_reference() will be called.
421 * For OS handles, the @a handle is removed from the Reactor. Unless
422 * @a masks includes ACE_Event_Handler::DONT_CALL,
423 * ACE_Event_Handler::handle_close() will be called with
424 * ACE_Event_Handler::NULL_MASK.
425 * ACE_Event_Handler::remove_reference() will also be called.
427 int remove_handler (ACE_HANDLE handle,
428 ACE_Reactor_Mask masks);
431 * Remove @a masks from @a event_handler registration.
433 * Same as remove_handler(ACE_HANDLE,ACE_Reactor_Mask), except
434 * @a handle comes from ACE_Event_Handler::get_handle().
436 int remove_handler (ACE_Event_Handler *event_handler,
437 ACE_Reactor_Mask masks);
440 * Remove @a masks from multiple <handle> registrations.
442 * Shorthand for calling remove_handler(ACE_HANDLE,ACE_Reactor_Mask)
443 * multiple times for the same @a masks but different @a handles.
445 int remove_handler (const ACE_Handle_Set &handles,
446 ACE_Reactor_Mask masks);
449 * Remove signal handler registration.
451 * Remove the ACE_Event_Handler currently associated with @a signum.
452 * Install the new disposition (if given) and return the previous
453 * disposition (if desired by the caller).
455 * Note that the registered handler's ACE_Event_Handler::handle_close ()
456 * callback will be called to indicate the signal handler has been removed.
457 * Unlike with I/O handles, there is no way to prevent this callback. The
458 * handle_close() callback can check the passed mask for the value
459 * ACE_Event_Handler::SIGNAL_MASK to tell when the callback is the result
460 * of a signal handler removal.
462 int remove_handler (int signum,
463 ACE_Sig_Action *new_disp,
464 ACE_Sig_Action *old_disp = 0,
465 int sigkey = -1);
468 * Remove multiple signal handler registrations.
470 * Shorthand for calling
471 * remove_handler(int,ACE_Sig_Action*,ACE_Sig_Action*,int) multiple
472 * times for every signal in @a sigset.
474 int remove_handler (const ACE_Sig_Set &sigset);
476 // = Suspend and resume Handlers.
479 * Suspend @a handle temporarily.
481 int suspend_handler (ACE_HANDLE handle);
484 * Suspend @a event_handler temporarily.
486 * Handle is obtained from ACE_Event_Handler::get_handle().
488 int suspend_handler (ACE_Event_Handler *event_handler);
491 * Suspend @a handles temporarily.
493 * Shorthand for calling suspend_handler(ACE_HANDLE) with multiple
494 * @a handles.
496 int suspend_handler (const ACE_Handle_Set &handles);
499 * Suspend all registered handles temporarily.
501 int suspend_handlers ();
504 * Resume @a handle.
506 int resume_handler (ACE_HANDLE handle);
509 * Resume @a event_handler.
511 * Handle is obtained from ACE_Event_Handler::get_handle().
513 int resume_handler (ACE_Event_Handler *event_handler);
516 * Resume @a handles.
518 * Shorthand for calling resume_handler(ACE_HANDLE) with multiple
519 * @a handles.
521 int resume_handler (const ACE_Handle_Set &handles);
524 * Resume all registered handles.
526 int resume_handlers ();
528 /// Does the reactor allow the application to resume the handle on
529 /// its own ie. can it pass on the control of handle resumption to
530 /// the application. A positive value indicates that the handlers
531 /// are application resumable. A value of 0 indicates otherwise.
532 int resumable_handler ();
534 // = Timer management.
537 * Schedule a timer event.
539 * Schedule a timer event that will expire after an @a delay amount
540 * of time. The return value of this method, a timer_id value,
541 * uniquely identifies the @a event_handler in the ACE_Reactor's
542 * internal list of timers. This timer_id value can be used to
543 * cancel the timer with the cancel_timer() call.
545 * Reactor will call ACE_Event_Handler::add_reference() on the
546 * handler. After the timeout occurs and
547 * ACE_Event_Handler::handle_timeout() has completed, the handler
548 * will be implicitly removed from the Reactor and
549 * ACE_Event_Handler::remove_reference() will be called.
551 * @see cancel_timer()
552 * @see reset_timer_interval()
554 * @param event_handler Event handler to schedule on reactor. The handler's
555 * handle_timeout() method will be called when this
556 * scheduled timer expires.
557 * @param arg Argument passed to the handle_timeout() method of
558 * event_handler.
559 * @param delay Time interval after which the timer will expire.
560 * @param interval Time interval for which the timer will be
561 * automatically rescheduled if the handle_timeout()
562 * callback does not return a value less than 0.
564 * @retval timer id, on success. The id can be used to
565 * cancel or reschedule this timer.
566 * @retval -1 on failure, with errno set.
568 virtual long schedule_timer (ACE_Event_Handler *event_handler,
569 const void *arg,
570 const ACE_Time_Value &delay,
571 const ACE_Time_Value &interval =
572 ACE_Time_Value::zero);
574 using ACE_Reactor_Timer_Interface::schedule_timer;
577 * Reset recurring timer interval.
579 * Resets the interval of the timer represented by @a timer_id to
580 * @a interval, which is specified in relative time to the current
581 * gettimeofday(). If @a interval is equal to
582 * ACE_Time_Value::zero, the timer will become a non-rescheduling
583 * timer. Returns 0 if successful, -1 if not.
585 * This change will not take effect until the next timeout.
587 virtual int reset_timer_interval (long timer_id,
588 const ACE_Time_Value &interval);
590 using ACE_Reactor_Timer_Interface::reset_timer_interval;
593 * Cancel timer.
595 * Cancel timer associated with @a timer_id that was returned from
596 * the schedule_timer() method. If arg is non-NULL then it will be
597 * set to point to the ``magic cookie'' argument passed in when the
598 * handler was registered. This makes it possible to free up the
599 * memory and avoid memory leaks. Returns 1 if cancellation
600 * succeeded and 0 if the @a timer_id wasn't found.
602 * On successful cancellation, ACE_Event_Handler::handle_close()
603 * will be called with ACE_Event_Handler::TIMER_MASK.
604 * ACE_Event_Handler::remove_reference() will also be called.
606 virtual int cancel_timer (long timer_id,
607 const void **arg = 0,
608 int dont_call_handle_close = 1);
611 * Cancel all timers associated with event handler.
613 * Shorthand for calling cancel_timer(long,const void **,int)
614 * multiple times for all timer associated with @a event_handler.
616 * ACE_Event_Handler::handle_close() will be called with
617 * ACE_Event_Handler::TIMER_MASK only once irrespective of the
618 * number of timers associated with the event handler.
619 * ACE_Event_Handler::remove_reference() will also be called once
620 * for every timer associated with the event handler.
622 * In case this operation is called with a nil event_handler
623 * it returns with 0 as the number of handlers cancelled.
625 * Returns number of handlers cancelled.
627 virtual int cancel_timer (ACE_Event_Handler *event_handler,
628 int dont_call_handle_close = 1);
630 // = High-level Event_Handler scheduling operations
632 /// Add @a masks_to_be_added to the @a event_handler's entry.
633 /// @a event_handler must already have been registered.
634 /// Note that this call does not cause the Reactor to re-examine
635 /// its set of handlers - the new masks will be noticed the next
636 /// time the Reactor waits for activity. If there is no other
637 /// activity expected, or you need immediate re-examination of the
638 /// wait masks, either call ACE_Reactor::notify after this call, or
639 /// use ACE_Reactor::register_handler instead.
640 int schedule_wakeup (ACE_Event_Handler *event_handler,
641 ACE_Reactor_Mask masks_to_be_added);
643 /// Add @a masks_to_be_added to the @a handle's entry. <event_handler>
644 /// associated with @a handle must already have been registered.
645 /// Note that this call does not cause the Reactor to re-examine
646 /// its set of handlers - the new masks will be noticed the next
647 /// time the Reactor waits for activity. If there is no other
648 /// activity expected, or you need immediate re-examination of
649 /// the wait masks, either call ACE_Reactor::notify after this call,
650 /// or use ACE_Reactor::register_handler instead.
651 int schedule_wakeup (ACE_HANDLE handle,
652 ACE_Reactor_Mask masks_to_be_added);
654 /// Clear @a masks_to_be_cleared from the @a event_handler's entry.
655 /// Note that this call does not cause the Reactor to re-examine
656 /// its set of handlers - the new masks will be noticed the next
657 /// time the Reactor waits for activity. If there is no other
658 /// activity expected, or you need immediate re-examination of
659 /// the wait masks, either call ACE_Reactor::notify after this
660 /// call, or use ACE_Reactor::register_handler instead.
661 int cancel_wakeup (ACE_Event_Handler *event_handler,
662 ACE_Reactor_Mask masks_to_be_cleared);
664 /// Clear @a masks_to_be_cleared from the @a handle's entry.
665 /// Note that this call does not cause the Reactor to re-examine
666 /// its set of handlers - the new masks will be noticed the next
667 /// time the Reactor waits for activity. If there is no other
668 /// activity expected, or you need immediate re-examination of
669 /// the wait masks, either call ACE_Reactor::notify after this
670 /// call, or use ACE_Reactor::register_handler instead.
671 int cancel_wakeup (ACE_HANDLE handle,
672 ACE_Reactor_Mask masks_to_be_cleared);
674 // = Notification methods.
677 * Dispatch user specified events.
679 * Handler will be dispatched irrespective of whether it is
680 * registered, not registered, or suspended in the Reactor.
682 * If user specified event is successfully queued,
683 * ACE_Event_Handler::add_reference() will be called. After the
684 * notify occurs and the upcall to the handler completes, the
685 * handler will be implicitly removed from the Reactor and
686 * ACE_Event_Handler::remove_reference() will be called. No other
687 * upcall reference counting is done.
689 * For I/O or OS events, the upcall is invoked with an
690 * ACE_INVALID_HANDLE.
692 * For timer events, the upcall is invoked with a null ACT.
694 * @param event_handler: IN - Handler on which the event will be
695 * dispatched.
696 * @param masks: IN - Events to be dispatched - multiple events can
697 * be OR'd together.
698 * @param timeout: INOUT - Relative time up to which to wait for
699 * user specified event to be queued. If tv is 0, wait
700 * indefinitely. When the call returns, tv has the time remaining
701 * after the call completes.
703 int notify (ACE_Event_Handler *event_handler = 0,
704 ACE_Reactor_Mask masks = ACE_Event_Handler::EXCEPT_MASK,
705 ACE_Time_Value *timeout = 0);
708 * Set the maximum number of times that ACE_Reactor will
709 * iterate and dispatch the ACE_Event_Handlers that are passed in
710 * via the notify queue before breaking out of its
711 * ACE_Message_Queue::dequeue() loop. By default, this is set to
712 * -1, which means "iterate until the queue is empty." Setting this
713 * to a value like "1 or 2" will increase "fairness" (and thus
714 * prevent starvation) at the expense of slightly higher dispatching
715 * overhead.
717 void max_notify_iterations (int iterations);
720 * Get the maximum number of times that the ACE_Reactor will
721 * iterate and dispatch the ACE_Event_Handler's that are passed in
722 * via the notify queue before breaking out of its
723 * ACE_Message_Queue::dequeue() loop.
725 int max_notify_iterations ();
728 * Purge any notifications pending in this reactor for the specified
729 * ACE_Event_Handler object. If @a eh == 0, all notifications for
730 * all handlers are removed (but not any notifications posted just
731 * to wake up the reactor itself). Returns the number of
732 * notifications purged. Returns -1 on error.
734 * After the purging occurs, the handler will be implicitly removed
735 * from the Reactor and ACE_Event_Handler::remove_reference() will
736 * be called.
738 int purge_pending_notifications (ACE_Event_Handler *eh,
739 ACE_Reactor_Mask =
740 ACE_Event_Handler::ALL_EVENTS_MASK);
742 // = Assorted helper methods.
745 * Return the Event_Handler associated with @a handle. Return 0 if
746 * @a handle is not registered.
748 * Reactor will call ACE_Event_Handler::add_reference() on the
749 * handler before returning it.
751 ACE_Event_Handler *find_handler (ACE_HANDLE handle);
754 * Check to see if @a handle is associated with a valid Event_Handler
755 * bound to @a mask. Return the @c event_handler associated with this
756 * @a handler if @a event_handler != 0.
758 * Reactor will call ACE_Event_Handler::add_reference() on the
759 * handler before returning it if @a event_handler != 0.
761 int handler (ACE_HANDLE handle,
762 ACE_Reactor_Mask mask,
763 ACE_Event_Handler **event_handler = 0);
766 * Check to see if @a signum is associated with a valid Event_Handler
767 * bound to a signal. Return the @a event_handler associated with
768 * this @c handler if @a event_handler != 0.
770 int handler (int signum,
771 ACE_Event_Handler **event_handler = 0);
773 /// Returns true if Reactor has been successfully initialized, else
774 /// false.
775 int initialized ();
777 /// Returns the current size of the Reactor's internal descriptor
778 /// table.
779 size_t size () const;
781 /// Returns a reference to the Reactor's internal lock.
782 ACE_Lock &lock ();
784 /// Wake up all threads in waiting in the event loop
785 void wakeup_all_threads ();
787 /// Transfers ownership of Reactor to the @a new_owner.
788 int owner (ACE_thread_t new_owner,
789 ACE_thread_t *old_owner = 0);
791 /// Return the ID of the "owner" thread.
792 int owner (ACE_thread_t *owner);
794 /// Set position of the owner thread.
795 void requeue_position (int position);
797 /// Get position of the owner thread.
798 int requeue_position ();
800 /// Get the existing restart value.
801 bool restart ();
803 /// Set a new value for restart and return the original value.
804 bool restart (bool r);
806 // = Low-level wait_set mask manipulation methods.
808 /// GET/SET/ADD/CLR the dispatch mask "bit" bound with the
809 /// @a event_handler and @a mask.
810 int mask_ops (ACE_Event_Handler *event_handler,
811 ACE_Reactor_Mask mask,
812 int ops);
814 /// GET/SET/ADD/CLR the dispatch MASK "bit" bound with the @a handle
815 /// and @a mask.
816 int mask_ops (ACE_HANDLE handle,
817 ACE_Reactor_Mask mask,
818 int ops);
820 // = Low-level ready_set mask manipulation methods.
821 /// GET/SET/ADD/CLR the ready "bit" bound with the @a event_handler
822 /// and @a mask.
823 int ready_ops (ACE_Event_Handler *event_handler,
824 ACE_Reactor_Mask mask,
825 int ops);
827 /// GET/SET/ADD/CLR the ready "bit" bound with the @a handle and @a mask.
828 int ready_ops (ACE_HANDLE handle,
829 ACE_Reactor_Mask mask,
830 int ops);
832 /// Get the implementation class
833 ACE_Reactor_Impl *implementation () const;
836 * Returns 0, if the size of the current message has been put in
837 * @a size returns -1, if not. ACE_HANDLE allows the reactor to
838 * check if the caller is valid. Used for CLASSIX Reactor
839 * implementation.
841 int current_info (ACE_HANDLE handle, size_t &msg_size);
843 /// Return true if we any event associations were made by the reactor
844 /// for the handles that it waits on, false otherwise.
845 bool uses_event_associations ();
847 /// Declare the dynamic allocation hooks.
848 ACE_ALLOC_HOOK_DECLARE;
850 /// Dump the state of the object.
851 void dump () const;
853 protected:
854 /// Set the implementation class.
855 void implementation (ACE_Reactor_Impl *implementation);
857 /// Delegation/implementation class that all methods will be
858 /// forwarded to.
859 ACE_Reactor_Impl *implementation_;
861 /// Flag used to indicate whether we are responsible for cleaning up
862 /// the implementation instance
863 bool delete_implementation_;
865 /// Pointer to a process-wide ACE_Reactor singleton.
866 static ACE_Reactor *reactor_;
868 /// Must delete the reactor_ singleton if true.
869 static bool delete_reactor_;
871 /// Deny access since member-wise won't work...
872 ACE_Reactor (const ACE_Reactor &) = delete;
873 ACE_Reactor &operator = (const ACE_Reactor &) = delete;
876 ACE_END_VERSIONED_NAMESPACE_DECL
878 #if defined (__ACE_INLINE__)
879 #include "ace/Reactor.inl"
880 #endif /* __ACE_INLINE__ */
882 #include /**/ "ace/post.h"
884 #endif /* ACE_REACTOR_H */