Nagios 4.5.4
Dev docs for Nagios core and neb-module hackers
Loading...
Searching...
No Matches
squeue.h
Go to the documentation of this file.
1#ifndef LIBNAGIOS_SQUEUE_H_INCLUDED
2#define LIBNAGIOS_SQUEUE_H_INCLUDED
3#include <sys/time.h>
4#include <time.h>
5#include "prqueue.h"
6/**
7 * @file squeue.h
8 * @brief Scheduling queue function declarations
9 *
10 * This library is based on the prqueue api, which implements a
11 * priority queue based on a binary heap, providing O(lg n) times
12 * for insert() and remove(), and O(1) time for peek().
13 * @note There is no "find". Callers must maintain pointers to their
14 * scheduled events if they wish to be able to remove them.
15 *
16 * @{
17 */
18
19/*
20 * All opaque types here.
21 * The prqueue library can be useful on its own though, so we
22 * don't block that from user view.
23 */
24typedef prqueue_t squeue_t;
25struct squeue_event;
26typedef struct squeue_event squeue_event;
27
28/**
29 * Options for squeue_destroy()'s flag parameter
30 */
31#define SQUEUE_FREE_DATA (1 << 0) /** Call free() on all data pointers */
32
33/**
34 * Get the scheduled runtime of this event
35 * @param[in] evt The event to get runtime of
36 * @return struct timeval on success, NULL on errors
37 */
38extern const struct timeval *squeue_event_runtime(squeue_event *evt);
39
40/**
41 * Get data of an squeue_event struct
42 * @param[in] evt The event to operate on
43 * @return The data object pointed to by the event
44 */
45extern void *squeue_event_data(squeue_event *evt);
46
47/**
48 * Creates a scheduling queue optimized for handling events within
49 * the given timeframe. Callers should take care to create a queue
50 * of a decent but not overly large size, as too small or too large
51 * a queue will impact performance negatively. A queue can hold any
52 * number of events. A good value for "horizon" would be the max
53 * seconds into the future one expects to schedule things, although
54 * with few scheduled items in that timeframe you'd be better off
55 * using a more narrow horizon.
56 *
57 * @param size Hint about how large this queue will get
58 * @return A pointer to a scheduling queue
59 */
60extern squeue_t *squeue_create(unsigned int size);
61
62/**
63 * Destroys a scheduling queue completely
64 * @param[in] q The doomed queue
65 * @param[in] flags Flags determining the level of destruction
66 */
67extern void squeue_destroy(squeue_t *q, int flags);
68
69/**
70 * Enqueue an event with microsecond precision.
71 * It's up to the caller to keep the event pointer in case he/she
72 * wants to remove the event from the queue later.
73 *
74 * @param q The scheduling queue to add to
75 * @param tv When this event should occur
76 * @param data Pointer to any kind of data
77 * @return The complete scheduled event
78 */
79extern squeue_event *squeue_add_tv(squeue_t *q, struct timeval *tv, void *data);
80
81/**
82 * Adds an event to the scheduling queue.
83 * See notes for squeue_add_tv() for details
84 *
85 * @param q The scheduling queue to add to
86 * @param when The unix timestamp when this event is to occur
87 * @param data Pointer to any kind of data
88 * @return The complete scheduled event
89 */
90extern squeue_event *squeue_add(squeue_t *q, time_t when, void *data);
91
92/**
93 * Adds an event to the scheduling queue with millisecond precision
94 * See notes on squeue_add_tv() for details
95 *
96 * @param[in] q The scheduling queue to add to
97 * @param[in] when Unix timestamp when this event should occur
98 * @param[in] usec Millisecond of above this event should occur
99 * @param[in] data Pointer to any kind of data
100 * @return NULL on errors. squeue_event pointer on success
101 */
102extern squeue_event *squeue_add_usec(squeue_t *q, time_t when, time_t usec, void *data);
103
104/**
105 * Adds an event to the scheduling queue with millisecond precision
106 * See notes on squeue_add_tv() for details
107 *
108 * @param[in] q The scheduling queue to add to
109 * @param[in] when Unix timestamp when this event should occur
110 * @param[in] msec Millisecond of above this event should occur
111 * @param[in] data Pointer to any kind of data
112 * @return NULL on errors. squeue_event pointer on success
113 */
114extern squeue_event *squeue_add_msec(squeue_t *q, time_t when, time_t msec, void *data);
115
116/**
117 * Change an event's priority to a new time.
118 *
119 * @param q The scheduling queue holding the event.
120 * @param evt The event to reschedule.
121 * @param tv When the event should be rescheduled to.
122 */
123extern void squeue_change_priority_tv(squeue_t *q, squeue_event *evt, struct timeval *tv);
124
125/**
126 * Returns the data of the next scheduled event from the scheduling
127 * queue without removing it from the queue.
128 *
129 * @param q The scheduling queue to peek into
130 */
131extern void *squeue_peek(squeue_t *q);
132
133/**
134 * Pops the next scheduled event from the scheduling queue and
135 * returns the data for it.
136 * This is equivalent to squeue_peek() + squeue_pop()
137 * @note This causes the squeue_event to be free()'d.
138 *
139 * @param q The scheduling queue to pop from
140 */
141extern void *squeue_pop(squeue_t *q);
142
143/**
144 * Removes the given event from the scheduling queue
145 * @note This causes the associated squeue_event() to be free()'d.
146 * @param[in] q The scheduling queue to remove from
147 * @param[in] evt The event to remove
148 */
149extern int squeue_remove(squeue_t *q, squeue_event *evt);
150
151/**
152 * Returns the number of events in the scheduling queue. This
153 * function never fails.
154 *
155 * @param[in] q The scheduling queue to inspect
156 * @return number of events in the inspected queue
157 */
158extern unsigned int squeue_size(squeue_t *q);
159
160
161/**
162 * Returns true if passed timeval is after the time for the event
163 *
164 * @param[in] evt The queue event to inspect
165 * @param[in] reftime The reference time to compare to the queue event time
166 * @return 1 if reftime > event time, 0 otherwise
167 */
168extern int squeue_evt_when_is_after(squeue_event *evt, struct timeval *reftime);
169#endif
170/** @} */
Priority Queue function declarations.
void * squeue_event_data(squeue_event *evt)
Get data of an squeue_event struct.
int squeue_remove(squeue_t *q, squeue_event *evt)
Removes the given event from the scheduling queue.
void * squeue_peek(squeue_t *q)
Returns the data of the next scheduled event from the scheduling queue without removing it from the q...
void squeue_change_priority_tv(squeue_t *q, squeue_event *evt, struct timeval *tv)
Change an event's priority to a new time.
squeue_event * squeue_add_msec(squeue_t *q, time_t when, time_t msec, void *data)
Adds an event to the scheduling queue with millisecond precision See notes on squeue_add_tv() for det...
int squeue_evt_when_is_after(squeue_event *evt, struct timeval *reftime)
Returns true if passed timeval is after the time for the event.
void squeue_destroy(squeue_t *q, int flags)
Destroys a scheduling queue completely.
squeue_t * squeue_create(unsigned int size)
Creates a scheduling queue optimized for handling events within the given timeframe.
squeue_event * squeue_add_tv(squeue_t *q, struct timeval *tv, void *data)
Enqueue an event with microsecond precision.
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 det...
unsigned int squeue_size(squeue_t *q)
Returns the number of events in the scheduling queue.
squeue_event * squeue_add(squeue_t *q, time_t when, void *data)
Adds an event to the scheduling queue.
void * squeue_pop(squeue_t *q)
Pops the next scheduled event from the scheduling queue and returns the data for it.
const struct timeval * squeue_event_runtime(squeue_event *evt)
Get the scheduled runtime of this event.
the priority queue handle
Definition prqueue.h:56