--- name: "ACE_Timer_Queue_T" 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_Timer_Queue_T" --- # ACE\_Timer\_Queue\_T(3) Provides an interface to timers. ## NAME ACE\_Timer\_Queue\_T - Provides an interface to timers. ## SYNOPSIS ``` #include template class ACE_Timer_Queue_T { public: typedef ACE_Timer_Queue_Iterator_T ITERATOR; ACE_Timer_Queue_T ( FUNCTOR *upcall_functor = 0, ACE_Free_List > *freelist = 0 ); virtual ~ACE_Timer_Queue_T (void); virtual int is_empty (void) const = 0; virtual const ACE_Time_Value &earliest_time (void) const = 0; virtual long schedule ( const TYPE &type, const void *act, const ACE_Time_Value &delay, const ACE_Time_Value &interval = ACE_Time_Value::zero ) = 0; virtual int reset_interval ( long timer_id, const ACE_Time_Value &interval ) = 0; virtual int cancel ( const TYPE &type, int dont_call_handle_close = 1 ) = 0; virtual int cancel ( long timer_id, const void **act = 0, int dont_call_handle_close = 1 ) = 0; virtual int expire (const ACE_Time_Value ¤t_time); int expire (void); ACE_Time_Value gettimeofday (void); void gettimeofday (ACE_Time_Value (*gettimeofday)(void)); virtual ACE_Time_Value *calculate_timeout (ACE_Time_Value *max); virtual ACE_Time_Value *calculate_timeout ( ACE_Time_Value *max, ACE_Time_Value *the_timeout ); void timer_skew (const ACE_Time_Value &skew); const ACE_Time_Value &timer_skew (void) const; ACE_LOCK &mutex (void); FUNCTOR &upcall_functor (void); virtual ITERATOR &iter (void) = 0; virtual ACE_Timer_Node_T *remove_first (void) = 0; virtual void dump (void) const; virtual ACE_Timer_Node_T *get_first (void) = 0; virtual void return_node (ACE_Timer_Node_T *); protected: void upcall ( TYPE &type, const void *act, const ACE_Time_Value &cur_time ); virtual void reschedule (ACE_Timer_Node_T *) = 0; virtual ACE_Timer_Node_T *alloc_node (void); virtual void free_node (ACE_Timer_Node_T *); ACE_LOCK mutex_; ACE_Free_List > *free_list_; ACE_Time_Value (*gettimeofday_)(void); FUNCTOR *upcall_functor_; int delete_upcall_functor_; int delete_free_list_; private: ACE_Time_Value timeout_; ACE_Time_Value timer_skew_; inline ACE_UNIMPLEMENTED_FUNC ( ACE_Timer_Queue_T (const ACE_Timer_Queue_T &) ); }; ``` ## DESCRIPTION This is an abstract base class that provides hook for implementing specialized policies such as ACE\_Timer\_List and ACE\_Timer\_Heap. ## Initialization and termination methods. ``` ACE_Timer_Queue_T ( FUNCTOR *upcall_functor = 0, ACE_Free_List > *freelist = 0 ); ``` Default constructor. upcall\_functor is the instance of the FUNCTOR to be used by the queue. If upcall\_functor is 0, Timer Queue will create a default FUNCTOR. freelist the freelist of timer nodes. If 0, then a default freelist will be created. ``` virtual ~ACE_Timer_Queue_T (void); ``` Destructor - make virtual for proper destruction of inherited classes. ``` virtual int is_empty (void) const = 0; ``` True if queue is empty, else false. ``` virtual const ACE_Time_Value &earliest_time (void) const = 0; ``` Returns the time of the earlier node in the Timer\_Queue. ``` virtual long schedule ( const TYPE &type, const void *act, const ACE_Time_Value &delay, const ACE_Time_Value &interval = ACE_Time_Value::zero ) = 0; ``` Schedule type that will expire after delay amount of time, which is specified in absolute time. If it expires then act is passed in as the value to the functor. If interval is != to ACE\_Time\_Value::zero then it is used to reschedule the type automatically, using relative time to the current gettimeofday. This method returns a timer\_id that uniquely identifies the the type entry in an internal list. This timer\_id can be used to cancel the 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 int reset_interval ( long timer_id, const ACE_Time_Value &interval ) = 0; ``` Resets the interval of the timer represented by timer\_id to interval, which is specified in relative time to the current gettimeofday. If interval is equal to ACE\_Time\_Value::zero, the timer will become a non-rescheduling timer. Returns 0 if successful, -1 if not. ``` virtual int cancel ( const TYPE &type, int dont_call_handle_close = 1 ) = 0; ``` Cancel all timer associated with type. If dont\_call\_handle\_close is 0 then the functor will be invoked, which typically invokes the handle\_close hook. Returns number of timers cancelled. ``` virtual int cancel ( long timer_id, const void **act = 0, int dont_call_handle_close = 1 ) = 0; ``` Cancel the single timer 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 timer was registered. This makes it possible to free up the memory and avoid memory leaks. If dont\_call\_handle\_close is 0 then the functor will be invoked, which typically calls the handle\_close hook. Returns 1 if cancellation succeeded and 0 if the timer\_id wasn't found. ``` virtual int expire (const ACE_Time_Value ¤t_time); ``` Run the functor for all timers whose values are = cur\_time. This does not account for timer\_skew. Returns the number of timers canceled. ``` int expire (void); ``` Run the functor for all timers whose values are = ACE\_OS::gettimeofday. Also accounts for timer\_skew. Returns the number of timers canceled. ``` ACE_Time_Value gettimeofday (void); ``` Returns the current time of day. This allows different implementations of the timer queue to use special high resolution timers. ``` void gettimeofday (ACE_Time_Value (*gettimeofday)(void)); ``` Allows applications to control how the timer queue gets the time of day. ``` virtual ACE_Time_Value *calculate_timeout (ACE_Time_Value *max); ``` Determine the next event to timeout. Returns max if there are no pending timers or if all pending timers are longer than max. ``` virtual ACE_Time_Value *calculate_timeout ( ACE_Time_Value *max, ACE_Time_Value *the_timeout ); ``` Determine the next event to timeout. Returns max if there are no pending timers or if all pending timers are longer than max. the\_timeout should be a pointer to storage for the timeout value, and this value is also returned. ## Set/get the timer skew for the Timer\_Queue. ``` void timer_skew (const ACE_Time_Value &skew); ``` ``` const ACE_Time_Value &timer_skew (void) const; ``` ``` ACE_LOCK &mutex (void); ``` Synchronization variable used by the queue ``` FUNCTOR &upcall_functor (void); ``` Accessor to the upcall functor ``` virtual ITERATOR &iter (void) = 0; ``` Returns a pointer to this ACE\_Timer\_Queue's iterator. ``` virtual ACE_Timer_Node_T *remove_first (void) = 0; ``` Removes the earliest node from the queue and returns it ``` virtual void dump (void) const; ``` Dump the state of a object. ``` virtual ACE_Timer_Node_T *get_first (void) = 0; ``` Reads the earliest node from the queue and returns it. ``` virtual void return_node (ACE_Timer_Node_T *); ``` Method used to return a timer node to the queue's ownership after it is returned by a method like remove\_first. ## Don't allow these operations for now. ``` inline ACE_UNIMPLEMENTED_FUNC ( ACE_Timer_Queue_T (const ACE_Timer_Queue_T &) ); ``` ## AUTHOR Doug Schmidt, Irfan Pyarali, and Darrell Brunsch ## LIBRARY ace