include/babeltrace/graph/notification-heap.h

   1 #ifndef BABELTRACE_GRAPH_NOTIFICATION_HEAP_H
   2 #define BABELTRACE_GRAPH_NOTIFICATION_HEAP_H
   3
   4 /*
   5  * Babeltrace - Notification Heap
   6  *
   7  * Copyright (c) 2011 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   8  * Copyright (c) 2016 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   9  *
  10  * Permission is hereby granted, free of charge, to any person obtaining a copy
  11  * of this software and associated documentation files (the "Software"), to deal
  12  * in the Software without restriction, including without limitation the rights
  13  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  14  * copies of the Software, and to permit persons to whom the Software is
  15  * furnished to do so, subject to the following conditions:
  16  *
  17  * The above copyright notice and this permission notice shall be included in
  18  * all copies or substantial portions of the Software.
  19  *
  20  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  21  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  23  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  24  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  25  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  26  * SOFTWARE.
  27  */
  28
  29 #include <stddef.h>
  30
  31 /* For bt_bool */
  32 #include <babeltrace/types.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 struct bt_notification;
  39
  40 /**
  41  * bt_notification_time_compare - Compare two notifications' timestamps
  42  *
  43  * Compare two notifications in the time domain. Return true if 'a' happened
  44  * prior to 'b'. In the case where both notifications are deemed to have
  45  * happened at the same time, an implementation-defined critarion shall be
  46  * used to order the notifications. This criterion shall ensure a consistent
  47  * ordering over multiple runs.
  48  */
  49 typedef bt_bool (*bt_notification_time_compare_func)(
  50                 struct bt_notification *a, struct bt_notification *b,
  51                 void *user_data);
  52
  53 /**
  54  * bt_notification_heap_create - create a new bt_notification heap.
  55  *
  56  * @comparator: Function to use for notification comparisons.
  57  *
  58  * Returns a new notification heap, NULL on error.
  59  */
  60 extern struct bt_notification_heap *bt_notification_heap_create(
  61                 bt_notification_time_compare_func comparator, void *user_data);
  62
  63 /**
  64  * bt_notification_heap_insert - insert an element into the heap
  65  *
  66  * @heap: the heap to be operated on
  67  * @notification: the notification to add
  68  *
  69  * Insert a notification into the heap.
  70  *
  71  * Returns 0 on success, a negative value on error.
  72  */
  73 extern int bt_notification_heap_insert(struct bt_notification_heap *heap,
  74                 struct bt_notification *notification);
  75
  76 /**
  77  * bt_notification_heap_peek - return the element on top of the heap.
  78  *
  79  * @heap: the heap to be operated on
  80  *
  81  * Returns the top element of the heap, without performing any modification
  82  * to the heap structure. Returns NULL if the heap is empty. The returned
  83  * notification must be bt_put() by the caller.
  84  */
  85 extern struct bt_notification *bt_notification_heap_peek(
  86                 struct bt_notification_heap *heap);
  87
  88 /**
  89  * bt_notification_heap_pop - remove the element sitting on top of the heap.
  90  * @heap: the heap to be operated on
  91  *
  92  * Returns the top element of the heap. The element is removed from the
  93  * heap. Returns NULL if the heap is empty. The returned notification must be
  94  * bt_put() by the caller.
  95  */
  96 extern struct bt_notification *bt_notification_heap_pop(
  97                 struct bt_notification_heap *heap);
  98
  99 #ifdef __cplusplus
 100 }
 101 #endif
 102
 103 #endif /* BABELTRACE_GRAPH_NOTIFICATION_HEAP_H */