Nagios
4.4.5
Dev docs for Nagios core and neb-module hackers
Main Page
Related Pages
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Macros
Pages
lib
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
/** @} */
Generated on Tue Oct 8 2019 00:17:26 for Nagios by
1.8.3.1