171 lines
5.5 KiB
C
171 lines
5.5 KiB
C
#ifndef LIBNAGIOS_SQUEUE_H_INCLUDED
|
|
#define LIBNAGIOS_SQUEUE_H_INCLUDED
|
|
#include <sys/time.h>
|
|
#include <time.h>
|
|
#include "pqueue.h"
|
|
/**
|
|
* @file squeue.h
|
|
* @brief Scheduling queue function declarations
|
|
*
|
|
* This library is based on the pqueue api, which implements a
|
|
* priority queue based on a binary heap, providing O(lg n) times
|
|
* for insert() and remove(), and O(1) time for peek().
|
|
* @note There is no "find". Callers must maintain pointers to their
|
|
* scheduled events if they wish to be able to remove them.
|
|
*
|
|
* @{
|
|
*/
|
|
|
|
/*
|
|
* All opaque types here.
|
|
* The pqueue library can be useful on its own though, so we
|
|
* don't block that from user view.
|
|
*/
|
|
typedef pqueue_t squeue_t;
|
|
struct squeue_event;
|
|
typedef struct squeue_event squeue_event;
|
|
|
|
/**
|
|
* Options for squeue_destroy()'s flag parameter
|
|
*/
|
|
#define SQUEUE_FREE_DATA (1 << 0) /** Call free() on all data pointers */
|
|
|
|
/**
|
|
* Get the scheduled runtime of this event
|
|
* @param[in] evt The event to get runtime of
|
|
* @return struct timeval on success, NULL on errors
|
|
*/
|
|
extern const struct timeval *squeue_event_runtime(squeue_event *evt);
|
|
|
|
/**
|
|
* Get data of an squeue_event struct
|
|
* @param[in] evt The event to operate on
|
|
* @return The data object pointed to by the event
|
|
*/
|
|
extern void *squeue_event_data(squeue_event *evt);
|
|
|
|
/**
|
|
* Creates a scheduling queue optimized for handling events within
|
|
* the given timeframe. Callers should take care to create a queue
|
|
* of a decent but not overly large size, as too small or too large
|
|
* a queue will impact performance negatively. A queue can hold any
|
|
* number of events. A good value for "horizon" would be the max
|
|
* seconds into the future one expects to schedule things, although
|
|
* with few scheduled items in that timeframe you'd be better off
|
|
* using a more narrow horizon.
|
|
*
|
|
* @param size Hint about how large this queue will get
|
|
* @return A pointer to a scheduling queue
|
|
*/
|
|
extern squeue_t *squeue_create(unsigned int size);
|
|
|
|
/**
|
|
* Destroys a scheduling queue completely
|
|
* @param[in] q The doomed queue
|
|
* @param[in] flags Flags determining the the level of destruction
|
|
*/
|
|
extern void squeue_destroy(squeue_t *q, int flags);
|
|
|
|
/**
|
|
* Enqueue an event with microsecond precision.
|
|
* It's up to the caller to keep the event pointer in case he/she
|
|
* wants to remove the event from the queue later.
|
|
*
|
|
* @param q The scheduling queue to add to
|
|
* @param tv When this event should occur
|
|
* @param data Pointer to any kind of data
|
|
* @return The complete scheduled event
|
|
*/
|
|
extern squeue_event *squeue_add_tv(squeue_t *q, struct timeval *tv, void *data);
|
|
|
|
/**
|
|
* Adds an event to the scheduling queue.
|
|
* See notes for squeue_add_tv() for details
|
|
*
|
|
* @param q The scheduling queue to add to
|
|
* @param when The unix timestamp when this event is to occur
|
|
* @param data Pointer to any kind of data
|
|
* @return The complete scheduled event
|
|
*/
|
|
extern squeue_event *squeue_add(squeue_t *q, time_t when, void *data);
|
|
|
|
/**
|
|
* Adds an event to the scheduling queue with millisecond precision
|
|
* See notes on squeue_add_tv() for details
|
|
*
|
|
* @param[in] q The scheduling queue to add to
|
|
* @param[in] when Unix timestamp when this event should occur
|
|
* @param[in] usec Millisecond of above this event should occur
|
|
* @param[in] data Pointer to any kind of data
|
|
* @return NULL on errors. squeue_event pointer on success
|
|
*/
|
|
extern squeue_event *squeue_add_usec(squeue_t *q, time_t when, time_t usec, void *data);
|
|
|
|
/**
|
|
* Adds an event to the scheduling queue with millisecond precision
|
|
* See notes on squeue_add_tv() for details
|
|
*
|
|
* @param[in] q The scheduling queue to add to
|
|
* @param[in] when Unix timestamp when this event should occur
|
|
* @param[in] msec Millisecond of above this event should occur
|
|
* @param[in] data Pointer to any kind of data
|
|
* @return NULL on errors. squeue_event pointer on success
|
|
*/
|
|
extern squeue_event *squeue_add_msec(squeue_t *q, time_t when, time_t msec, void *data);
|
|
|
|
/**
|
|
* Change an event's priority to a new time.
|
|
*
|
|
* @param q The scheduling queue holding the event.
|
|
* @param evt The event to reschedule.
|
|
* @param tv When the event should be rescheduled to.
|
|
*/
|
|
extern void squeue_change_priority_tv(squeue_t *q, squeue_event *evt, struct timeval *tv);
|
|
|
|
/**
|
|
* Returns the data of the next scheduled event from the scheduling
|
|
* queue without removing it from the queue.
|
|
*
|
|
* @param q The scheduling queue to peek into
|
|
*/
|
|
extern void *squeue_peek(squeue_t *q);
|
|
|
|
/**
|
|
* Pops the next scheduled event from the scheduling queue and
|
|
* returns the data for it.
|
|
* This is equivalent to squeue_peek() + squeue_pop()
|
|
* @note This causes the squeue_event to be free()'d.
|
|
*
|
|
* @param q The scheduling queue to pop from
|
|
*/
|
|
extern void *squeue_pop(squeue_t *q);
|
|
|
|
/**
|
|
* Removes the given event from the scheduling queue
|
|
* @note This causes the associated squeue_event() to be free()'d.
|
|
* @param[in] q The scheduling queue to remove from
|
|
* @param[in] evt The event to remove
|
|
*/
|
|
extern int squeue_remove(squeue_t *q, squeue_event *evt);
|
|
|
|
/**
|
|
* Returns the number of events in the scheduling queue. This
|
|
* function never fails.
|
|
*
|
|
* @param[in] q The scheduling queue to inspect
|
|
* @return number of events in the inspected queue
|
|
*/
|
|
extern unsigned int squeue_size(squeue_t *q);
|
|
|
|
|
|
/**
|
|
* Returns true if passed timeval is after the time for the event
|
|
*
|
|
* @param[in] evt The queue event to inspect
|
|
* @param[in] reftime The reference time to compare to the queue event time
|
|
* @return 1 if reftime > event time, 0 otherwise
|
|
*/
|
|
extern int squeue_evt_when_is_after(squeue_event *evt, struct timeval *reftime);
|
|
#endif
|
|
/** @} */
|