Nagios  4.4.3
Dev docs for Nagios core and neb-module hackers
squeue.h File Reference

Scheduling queue function declarations. More...

#include <sys/time.h>
#include <time.h>
#include "pqueue.h"

Go to the source code of this file.

#define SQUEUE_FREE_DATA   (1 << 0) /** Call free() on all data pointers */
 Options for squeue_destroy()'s flag parameter.
 
typedef pqueue_t squeue_t
 
typedef struct squeue_event squeue_event
 
const struct timeval * squeue_event_runtime (squeue_event *evt)
 Get the scheduled runtime of this event. More...
 
void * squeue_event_data (squeue_event *evt)
 Get data of an squeue_event struct. More...
 
squeue_tsqueue_create (unsigned int size)
 Creates a scheduling queue optimized for handling events within the given timeframe. More...
 
void squeue_destroy (squeue_t *q, int flags)
 Destroys a scheduling queue completely. More...
 
squeue_event * squeue_add_tv (squeue_t *q, struct timeval *tv, void *data)
 Enqueue an event with microsecond precision. More...
 
squeue_event * squeue_add (squeue_t *q, time_t when, void *data)
 Adds an event to the scheduling queue. More...
 
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. More...
 
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 details. More...
 
void squeue_change_priority_tv (squeue_t *q, squeue_event *evt, struct timeval *tv)
 Change an event's priority to a new time. More...
 
void * squeue_peek (squeue_t *q)
 Returns the data of the next scheduled event from the scheduling queue without removing it from the queue. More...
 
void * squeue_pop (squeue_t *q)
 Pops the next scheduled event from the scheduling queue and returns the data for it. More...
 
int squeue_remove (squeue_t *q, squeue_event *evt)
 Removes the given event from the scheduling queue. More...
 
unsigned int squeue_size (squeue_t *q)
 Returns the number of events in the scheduling queue. More...
 
int squeue_evt_when_is_after (squeue_event *evt, struct timeval *reftime)
 Returns true if passed timeval is after the time for the event. More...
 

Detailed Description

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.

Function Documentation

◆ squeue_add()

squeue_event* squeue_add ( squeue_t q,
time_t  when,
void *  data 
)

Adds an event to the scheduling queue.

See notes for squeue_add_tv() for details

Parameters
qThe scheduling queue to add to
whenThe unix timestamp when this event is to occur
dataPointer to any kind of data
Returns
The complete scheduled 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 details.

Parameters
[in]qThe scheduling queue to add to
[in]whenUnix timestamp when this event should occur
[in]msecMillisecond of above this event should occur
[in]dataPointer to any kind of data
Returns
NULL on errors. squeue_event pointer on success

◆ squeue_add_tv()

squeue_event* squeue_add_tv ( squeue_t q,
struct timeval *  tv,
void *  data 
)

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.

Parameters
qThe scheduling queue to add to
tvWhen this event should occur
dataPointer to any kind of data
Returns
The complete scheduled event

◆ 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 details.

Parameters
[in]qThe scheduling queue to add to
[in]whenUnix timestamp when this event should occur
[in]usecMillisecond of above this event should occur
[in]dataPointer to any kind of data
Returns
NULL on errors. squeue_event pointer on success

◆ 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.

Parameters
qThe scheduling queue holding the event.
evtThe event to reschedule.
tvWhen the event should be rescheduled to.

◆ squeue_create()

squeue_t* squeue_create ( unsigned int  size)

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.

Parameters
sizeHint about how large this queue will get
Returns
A pointer to a scheduling queue

◆ squeue_destroy()

void squeue_destroy ( squeue_t q,
int  flags 
)

Destroys a scheduling queue completely.

Parameters
[in]qThe doomed queue
[in]flagsFlags determining the the level of destruction

◆ squeue_event_data()

void* squeue_event_data ( squeue_event *  evt)

Get data of an squeue_event struct.

Parameters
[in]evtThe event to operate on
Returns
The data object pointed to by the event

◆ squeue_event_runtime()

const struct timeval* squeue_event_runtime ( squeue_event *  evt)

Get the scheduled runtime of this event.

Parameters
[in]evtThe event to get runtime of
Returns
struct timeval on success, NULL on errors

◆ 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.

Parameters
[in]evtThe queue event to inspect
[in]reftimeThe reference time to compare to the queue event time
Returns
1 if reftime > event time, 0 otherwise

◆ 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 queue.

Parameters
qThe scheduling queue to peek into

◆ squeue_pop()

void* squeue_pop ( 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.
Parameters
qThe scheduling queue to pop from

◆ squeue_remove()

int squeue_remove ( squeue_t q,
squeue_event *  evt 
)

Removes the given event from the scheduling queue.

Note
This causes the associated squeue_event() to be free()'d.
Parameters
[in]qThe scheduling queue to remove from
[in]evtThe event to remove

◆ squeue_size()

unsigned int squeue_size ( squeue_t q)

Returns the number of events in the scheduling queue.

This function never fails.

Parameters
[in]qThe scheduling queue to inspect
Returns
number of events in the inspected queue