1+ /// @file fcheap.h
2+ /// @author Nikolaos D. Kallimanis
3+ /// @brief This file exposes the API of the FCHeap, 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 the flat-combining object
5+ /// provided by `fc.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/fcheapbench.c file.
8+ ///
9+ /// @copyright Copyright (c) 2024
10+ #ifndef _FCHEAP_H_
11+ #define _FCHEAP_H_
12+
13+ #include <limits.h>
14+ #include <fc.h>
15+
16+ #include <serialheap.h>
17+
18+
19+ /// @brief The type of heap is max-heap
20+ #define FCHEAP_TYPE_MIN SYNCH_HEAP_TYPE_MIN
21+ /// @brief The type of heap is min-heap
22+ #define FCHEAP_TYPE_MAX SYNCH_HEAP_TYPE_MAX
23+
24+ /// @brief FCHeapStruct stores the state of an instance of the FCHeap concurrent heap implementation.
25+ /// FCHeapStruct should be initialized using the FCHeapStructInit function.
26+ typedef struct FCHeapStruct {
27+ /// @brief An instance of FC.
28+ FCStruct heap CACHE_ALIGN ;
29+ /// @brief An instance of a serial heap implementation (see `serialheap.h`).
30+ SerialHeapStruct state ;
31+ } FCHeapStruct ;
32+
33+ /// @brief FCHeapThreadState stores each thread's local state for a single instance of FCHeap.
34+ /// For each instance of FCHeap, a discrete instance of FCHeapThreadStateState should be used.
35+ typedef struct FCHeapThreadState {
36+ /// @brief A FCThreadState struct for the instance of FC.
37+ FCThreadState thread_state ;
38+ } FCHeapThreadState ;
39+
40+ /// @brief This function initializes an instance of the FCHeap 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 FCHeap 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 FCHEAP_TYPE_MIN,
47+ /// the type of heap is min. In case that the argument is equal to FCHEAP_TYPE_MAX, the type of heap is max.
48+ /// @param nthreads The number of threads that will use the FCHeap concurrent heap implementation.
49+ void FCHeapInit (FCHeapStruct * 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 FCHeap concurrent heap implementation.
52+ ///
53+ /// @param heap_struct A pointer to an instance of the FCHeap concurrent heap implementation.
54+ /// @param lobject_struct A pointer to thread's local state of FCHeap.
55+ /// @param pid The pid of the calling thread.
56+ void FCHeapThreadStateInit (FCHeapStruct * heap_struct , FCHeapThreadState * 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 FCHeap concurrent heap implementation.
61+ /// @param lobject_struct A pointer to thread's local state of FCHeap.
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 FCHeapInsert (FCHeapStruct * heap_struct , FCHeapThreadState * 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 FCHeap concurrent heap implementation.
69+ /// @param lobject_struct A pointer to thread's local state of FCHeap.
70+ /// @param pid The pid of the calling thread.
71+ /// @return The value of the removed element. In case that the heap is empty `SYNCH_HEAP_EMPTY` is returned.
72+ SynchHeapElement FCHeapDeleteMin (FCHeapStruct * heap_struct , FCHeapThreadState * 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 FCHeap concurrent heap implementation.
77+ /// @param lobject_struct A pointer to thread's local state of FCHeap.
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 `SYNCH_HEAP_EMPTY` is returned.
80+ SynchHeapElement FCHeapGetMin (FCHeapStruct * heap_struct , FCHeapThreadState * lobject_struct , int pid );
81+
82+ #endif
0 commit comments