1+ /// @file ccheap.h
2+ /// @author Nikolaos D. Kallimanis
3+ /// @brief This file exposes the API of the CCHeap, which is a concurrent heap object of fixed size.
4+ /// The provided implementation uses the dynamic serial heap implementation provided by `serialheap.h` combined with CCSynch combining object
5+ /// provided by `ccsynch.h`. This dynamic heap implementation is based on the static heap implementation provided
6+ /// in https://github.com/ConcurrentDistributedLab/PersistentCombining repository.
7+ /// An example of use of this API is provided in benchmarks/ccheapbench.c file.
8+ ///
9+ /// @copyright Copyright (c) 2024
10+ #ifndef _CCHEAP_H_
11+ #define _CCHEAP_H_
12+
13+ #include <limits.h>
14+ #include <ccsynch.h>
15+
16+ #include <serialheap.h>
17+
18+
19+ /// @brief The type of heap is max-heap
20+ #define CCHEAP_TYPE_MIN SYNCH_HEAP_TYPE_MIN
21+ /// @brief The type of heap is min-heap
22+ #define CCHEAP_TYPE_MAX SYNCH_HEAP_TYPE_MAX
23+
24+ /// @brief CCHeapStruct stores the state of an instance of the CCHeap concurrent heap implementation.
25+ /// CCHeapStruct should be initialized using the CCHeapStructInit function.
26+ typedef struct CCHeapStruct {
27+ /// @brief An instance of CCSynch.
28+ CCSynchStruct heap CACHE_ALIGN ;
29+ /// @brief An instance of a serial heap implementation (see `serialheap.h`).
30+ SerialHeapStruct state ;
31+ } CCHeapStruct ;
32+
33+ /// @brief CCHeapThreadState stores each thread's local state for a single instance of CCHeap.
34+ /// For each instance of CCHeap, a discrete instance of CCHeapThreadStateState should be used.
35+ typedef struct CCHeapThreadState {
36+ /// @brief A CCSynchThreadState struct for the instance of CCSynch.
37+ CCSynchThreadState thread_state ;
38+ } CCHeapThreadState ;
39+
40+ /// @brief This function initializes an instance of the CCHeap concurrent heap implementation.
41+ ///
42+ /// This function should be called once (by a single thread) before any other thread tries to
43+ /// apply any operation on the heap object.
44+ ///
45+ /// @param heap_struct A pointer to an instance of the CCHeap concurrent heap implementation.
46+ /// @param type Identifies the type of heap (i.e. min-heap or max-heap). In case that the argument is equal to CCHEAP_TYPE_MIN,
47+ /// the type of heap is min. In case that the argument is equal to CCHEAP_TYPE_MAX, the type of heap is max.
48+ /// @param nthreads The number of threads that will use the CCHeap concurrent heap implementation.
49+ void CCHeapInit (CCHeapStruct * heap_struct , uint32_t type , uint32_t nthreads );
50+
51+ /// @brief This function should be called once by every thread before it applies any operation to the CCHeap concurrent heap implementation.
52+ ///
53+ /// @param heap_struct A pointer to an instance of the CCHeap concurrent heap implementation.
54+ /// @param lobject_struct A pointer to thread's local state of CCHeap.
55+ /// @param pid The pid of the calling thread.
56+ void CCHeapThreadStateInit (CCHeapStruct * heap_struct , CCHeapThreadState * lobject_struct , int pid );
57+
58+ /// @brief This function inserts a new element with value `arg` to the heap.
59+ ///
60+ /// @param heap_struct A pointer to an instance of the CCHeap concurrent heap implementation.
61+ /// @param lobject_struct A pointer to thread's local state of CCHeap.
62+ /// @param arg The value of the element that will be inserted in the heap.
63+ /// @param pid The pid of the calling thread.
64+ void CCHeapInsert (CCHeapStruct * heap_struct , CCHeapThreadState * lobject_struct , SynchHeapElement arg , int pid );
65+
66+ /// @brief This function removes the element of the heap that has the minimum value.
67+ ///
68+ /// @param heap_struct A pointer to an instance of the CCHeap concurrent heap implementation.
69+ /// @param lobject_struct A pointer to thread's local state of CCHeap.
70+ /// @param pid The pid of the calling thread.
71+ /// @return The value of the removed element. In case that the heap is empty `EMPTY_HEAP` is returned.
72+ SynchHeapElement CCHeapDeleteMin (CCHeapStruct * heap_struct , CCHeapThreadState * lobject_struct , int pid );
73+
74+ /// @brief This function returns (without removing) the element of the heap that has the minimum value.
75+ ///
76+ /// @param heap_struct A pointer to an instance of the CCHeap concurrent heap implementation.
77+ /// @param lobject_struct A pointer to thread's local state of CCHeap.
78+ /// @param pid The pid of the calling thread.
79+ /// @return The value of the minimum element contained in the heap. In case that the heap is empty `EMPTY_HEAP` is returned.
80+ SynchHeapElement CCHeapGetMin (CCHeapStruct * heap_struct , CCHeapThreadState * lobject_struct , int pid );
81+
82+ #endif
0 commit comments