← Back to branch summary

~ubuntu-branches/ubuntu/trusty/geis/trusty

« back to all changes in this revision

Viewing changes to libgeis/geis_event_queue.h

  • Committer: Package Import Robot
  • Author(s): Chase Douglas
  • Date: 2012-07-30 08:51:42 UTC
  • Revision ID: package-import@ubuntu.com-20120730085142-jrc33ygjvt0ob1wl
Tags: upstream-2.2.11
Import upstream version 2.2.11

Show diffs side-by-side

added added

removed removed

Lines of Context:
libgeis/geis_event_queue.h
 
1
/**
 
2
 * @file geis_event_queue.h
 
3
 * @brief internal Geis event queue public interface
 
4
 *
 
5
 * Copyright 2010 Canonical Ltd.
 
6
 *
 
7
 * This library is free software; you can redistribute it and/or modify it under
 
8
 * the terms of the GNU Lesser General Public License as published by the Free
 
9
 * Software Foundation; either version 3 of the License, or (at your option) any
 
10
 * later version.
 
11
 *
 
12
 * This library is distributed in the hope that it will be useful, but WITHOUT
 
13
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 
14
 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 
15
 * details.
 
16
 *
 
17
 * You should have received a copy of the GNU Lesser General Public License
 
18
 * along with this program; if not, write to the Free Software Foundation, Inc.,
 
19
 * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 
20
 */
 
21
#ifndef GEIS_EVENT_QUEUE_H_
 
22
#define GEIS_EVENT_QUEUE_H_
 
23
 
 
24
#include <geis/geis.h>
 
25
 
 
26
 
 
27
/**
 
28
 * A container for event_queues.
 
29
 *
 
30
 * This is a simple FIFO container for opaque GeisEvent objetcs.
 
31
 *
 
32
 * This container does not asssume ownership of the contained GeisEvents.
 
33
 * Someone creates the events and pushes them into the queue, and someone pulls
 
34
 * the events off the queue and does something with them.
 
35
 *
 
36
 * The current implementation uses a pooled caching strategy for dynamic
 
37
 * allocations to minimize overhead due to high-turnover usage.
 
38
 */
 
39
typedef struct _GeisEventQueue *GeisEventQueue;
 
40
 
 
41
 
 
42
/**
 
43
 * Creates a new Geis Event queue.
 
44
 */
 
45
GeisEventQueue geis_event_queue_new();
 
46
 
 
47
/**
 
48
 * Destroys a Geis Event queue.
 
49
 *
 
50
 * @param[in] queue  The event queue.
 
51
 *
 
52
 * This function empties the queue and destroys any GeisEvents malingering
 
53
 * therein, then destroys the queue itself.
 
54
 */
 
55
void geis_event_queue_delete(GeisEventQueue queue);
 
56
 
 
57
/**
 
58
 * Pushes a new event onto the back of the event queue.
 
59
 *
 
60
 * @param[in] queue  The event queue.
 
61
 *
 
62
 * @retval GEIS_STATUS_SUCCESS        Normal successful completion.
 
63
 *
 
64
 * @retval GEIS_STATUS_UNKNOWN_ERROR  Something bad happened.
 
65
 */
 
66
GeisStatus geis_event_queue_enqueue(GeisEventQueue queue, GeisEvent event);
 
67
 
 
68
/**
 
69
 * Indicates if an event queue is empty.
 
70
 *
 
71
 * @param[in]  queue  The event queue.
 
72
 *
 
73
 * @returns GEIS_TRUE if the queue contains no events, GEIS_FALSE otherwise.
 
74
 */
 
75
GeisBoolean geis_event_queue_is_empty(GeisEventQueue queue);
 
76
 
 
77
/**
 
78
 * Pops the event off the front of the queue.
 
79
 *
 
80
 * @param[in] queue  The event queue.
 
81
 *
 
82
 * @returns the next GeisEvent or NULL of the queue is empty.
 
83
 */
 
84
GeisEvent geis_event_queue_dequeue(GeisEventQueue queue);
 
85
 
 
86
/**
 
87
 * Prototype for GEIS event matching predicate functions.
 
88
 */
 
89
typedef GeisBoolean (*GeisEventMatch)(GeisEvent event, void *context);
 
90
 
 
91
/**
 
92
 * Removes events from a queue of they match a condition.
 
93
 *
 
94
 * @param[in] queue     The event queue.
 
95
 * @param[in] matching  A unary predicate function to indicate the events to be
 
96
 *                      removed.
 
97
 * @param[in] context   An application-specific context value to be passed to
 
98
 *                      the matching function.
 
99
 */
 
100
void geis_event_queue_remove_if(GeisEventQueue  queue,
 
101
                                GeisEventMatch  matching,
 
102
                                void           *context);
 
103
 
 
104
#endif /* GEIS_EVENT_QUEUE_H_ */