## NAME

ACE_Timer_Heap_T - Provides a very fast and predictable timer implementation.

## SYNOPSIS

    #include <ace/Timer_Heap_T.h>

    template<class TYPE, class FUNCTOR, class ACE_LOCK>
    class ACE_Timer_Heap_T :
      public ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK>
    {
      public:
            typedef ACE_Timer_Heap_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> HEAP_ITERATOR;

        friend class ACE_Timer_Heap_Iterator_T<TYPE, FUNCTOR, ACE_LOCK>;
        typedef ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> INHERITED;
        ACE_Timer_Heap_T (
            size_t size,
            int preallocated = 0,
            FUNCTOR *upcall_functor = 0,
            ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0
            );
        ACE_Timer_Heap_T (
            FUNCTOR *upcall_functor = 0,
            ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0
            );
        virtual ~ACE_Timer_Heap_T (void);
        virtual int is_empty (void) const;
        virtual const ACE_Time_Value &earliest_time (void) const;
        virtual long schedule (
            const TYPE &type,
            const void *act,
            const ACE_Time_Value &delay,
            const ACE_Time_Value &interval = ACE_Time_Value::zero
            );
        virtual int cancel (
            const TYPE &type,
            int dont_call_handle_close = 1
            );
        virtual int cancel (
            long timer_id,
            const void **act = 0,
            int dont_call_handle_close = 1
            );
        virtual ACE_Timer_Queue_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> &iter (
            void
            );
        ACE_Timer_Node_T <TYPE> *remove_first (void);
        virtual void dump (void) const;
        virtual ACE_Timer_Node_T<TYPE> *get_first (void);
      protected:
        virtual void reschedule (ACE_Timer_Node_T<TYPE> *);
        virtual ACE_Timer_Node_T<TYPE> *alloc_node (void);
        virtual void free_node (ACE_Timer_Node_T<TYPE> *);
      private:
        ACE_Timer_Node_T<TYPE> *remove (size_t slot);
        void insert (ACE_Timer_Node_T<TYPE> *new_node);
        void grow_heap (void);
        void reheap_up (
            ACE_Timer_Node_T<TYPE> *new_node,
            size_t slot,
            size_t parent
            );
        void reheap_down (
            ACE_Timer_Node_T<TYPE> *moved_node,
            size_t slot,
            size_t child
            );
        void copy (int slot, ACE_Timer_Node_T<TYPE> *moved_node);
        int timer_id (void);
        int pop_freelist (void);
        void push_freelist (int old_id);
        size_t max_size_;
        size_t cur_size_;
        HEAP_ITERATOR *iterator_;
        ACE_Timer_Node_T<TYPE> **heap_;
        long *timer_ids_;
        long timer_ids_freelist_;
        ACE_Timer_Node_T<TYPE> *preallocated_nodes_;
        ACE_Timer_Node_T<TYPE> *preallocated_nodes_freelist_;
            ACE_Unbounded_Set<ACE_Timer_Node_T<TYPE> *> preallocated_node_set_;

        inline ACE_UNIMPLEMENTED_FUNC (
            ACE_Timer_Heap_T (const ACE_Timer_Heap_T<TYPE, FUNCTOR, ACE_LOCK> &)
            );
    };

## DESCRIPTION

This implementation uses a heap-based callout queue of absolute times. Therefore, in the average and worst case, scheduling, canceling, and expiring timers is O(log N) (where N is the total number of timers). In addition, we can also preallocate as many `ACE_Timer_Nodes` as there are slots in the heap. This allows us to completely remove the need for dynamic memory allocation, which is important for real-time systems.

## Initialization and termination methods.

    ACE_Timer_Heap_T (
        size_t size,
        int preallocated = 0,
        FUNCTOR *upcall_functor = 0,
        ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0
        );

The Constructor creates a heap with `size` elements. If `preallocated` is non-0 then we'll pre-allocate all the memory for the `ACE_Timer_Nodes`. This saves time and is more predictable (though it requires more space). Otherwise, we'll just allocate the nodes as we need them. This can also take in a upcall functor and freelist (if 0, then defaults will be created)

    ACE_Timer_Heap_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 Heap will create a default FUNCTOR. `freelist` the freelist of timer nodes. If 0, then a default freelist will be created. The default size will be ACE_DEFAULT_TIMERS and there will be no preallocation.

    virtual ~ACE_Timer_Heap_T (void);

Destructor.

    virtual int is_empty (void) const;

True if heap is empty, else false.

    virtual const ACE_Time_Value &earliest_time (void) const;

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

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

Cancel all timer associated with `type`. If `dont_call` is 0 then the `functor` will be invoked. Returns number of timers cancelled.

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

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` is 0 then the `functor` will be invoked. Returns 1 if cancellation succeeded and 0 if the `timer_id` wasn't found.

    virtual ACE_Timer_Queue_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> &iter (
        void
        );

Returns a pointer to this `ACE_Timer_Queue`'s iterator.

    ACE_Timer_Node_T <TYPE> *remove_first (void);

Removes the earliest node from the queue and returns it

    virtual void dump (void) const;

Dump the state of an object.

    virtual ACE_Timer_Node_T<TYPE> *get_first (void);

Reads the earliest node from the queue and returns it.

## Don't allow these operations for now.

    inline ACE_UNIMPLEMENTED_FUNC (
        ACE_Timer_Heap_T (const ACE_Timer_Heap_T<TYPE, FUNCTOR, ACE_LOCK> &)
        );

## AUTHOR

Doug Schmidt

## LIBRARY

ace