Nagios  4.4.6
Dev docs for Nagios core and neb-module hackers
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 "pqueue.h"
6 /**
7  * @file squeue.h
8  * @brief Scheduling queue function declarations
9  *
10  * This library is based on the pqueue 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 pqueue library can be useful on its own though, so we
22  * don't block that from user view.
23  */
24 typedef pqueue_t squeue_t;
25 struct squeue_event;
26 typedef 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  */
38 extern 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  */
45 extern 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  */
60 extern 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 the level of destruction
66  */
67 extern 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  */
79 extern 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  */
90 extern 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  */
102 extern 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  */
114 extern 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  */
123 extern 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  */
131 extern 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  */
141 extern 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  */
149 extern 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  */
158 extern 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  */
168 extern int squeue_evt_when_is_after(squeue_event *evt, struct timeval *reftime);
169 #endif
170 /** @} */
squeue_destroy
void squeue_destroy(squeue_t *q, int flags)
Destroys a scheduling queue completely.
squeue_add_usec
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...
squeue_evt_when_is_after
int squeue_evt_when_is_after(squeue_event *evt, struct timeval *reftime)
Returns true if passed timeval is after the time for the event.
squeue_add_msec
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...
squeue_pop
void * squeue_pop(squeue_t *q)
Pops the next scheduled event from the scheduling queue and returns the data for it.
squeue_event_data
void * squeue_event_data(squeue_event *evt)
Get data of an squeue_event struct.
squeue_event_runtime
const struct timeval * squeue_event_runtime(squeue_event *evt)
Get the scheduled runtime of this event.
squeue_remove
int squeue_remove(squeue_t *q, squeue_event *evt)
Removes the given event from the scheduling queue.
pqueue_t
the priority queue handle
Definition: pqueue.h:55
squeue_create
squeue_t * squeue_create(unsigned int size)
Creates a scheduling queue optimized for handling events within the given timeframe.
squeue_size
unsigned int squeue_size(squeue_t *q)
Returns the number of events in the scheduling queue.
squeue_add
squeue_event * squeue_add(squeue_t *q, time_t when, void *data)
Adds an event to the scheduling queue.
pqueue.h
Priority Queue function declarations.
squeue_peek
void * squeue_peek(squeue_t *q)
Returns the data of the next scheduled event from the scheduling queue without removing it from the q...
squeue_add_tv
squeue_event * squeue_add_tv(squeue_t *q, struct timeval *tv, void *data)
Enqueue an event with microsecond precision.
squeue_change_priority_tv
void squeue_change_priority_tv(squeue_t *q, squeue_event *evt, struct timeval *tv)
Change an event's priority to a new time.