## NAME

ACE_Timer_Queue_T - Provides an interface to timers.

## SYNOPSIS

    #include <ace/Timer_Queue_T.h>

    template<class TYPE, class FUNCTOR, class ACE_LOCK>
    class ACE_Timer_Queue_T
    {
      public:
            typedef ACE_Timer_Queue_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> ITERATOR;

        ACE_Timer_Queue_T (
            FUNCTOR *upcall_functor = 0,
            ACE_Free_List<ACE_Timer_Node_T <TYPE> > *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 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 &current_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<TYPE> *remove_first (void) = 0;
        virtual void dump (void) const;
        virtual ACE_Timer_Node_T<TYPE> *get_first (void) = 0;
        virtual void return_node (ACE_Timer_Node_T<TYPE> *);
      protected:
        void upcall (
            TYPE &type,
            const void *act,
            const ACE_Time_Value &cur_time
            );
        virtual void reschedule (ACE_Timer_Node_T<TYPE> *) = 0;
        virtual ACE_Timer_Node_T<TYPE> *alloc_node (void);
        virtual void free_node (ACE_Timer_Node_T<TYPE> *);
        ACE_LOCK mutex_;
        ACE_Free_List<ACE_Timer_Node_T<TYPE> > *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<TYPE, FUNCTOR, ACE_LOCK> &)
            );
    };

## 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<ACE_Timer_Node_T <TYPE> > *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. 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. 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 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 &current_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<TYPE> *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<TYPE> *get_first (void) = 0;

Reads the earliest node from the queue and returns it.

    virtual void return_node (ACE_Timer_Node_T<TYPE> *);

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<TYPE, FUNCTOR, ACE_LOCK> &)
        );

## AUTHOR

Doug Schmidt, Irfan Pyarali, and Darrell Brunsch

## LIBRARY

ace