globus_priority_q(3)

💖 globus_priority_q 💖

okay bestie, buckle up — this is globus_priority_q(3) from the Library Functions Manual, and it's literally the priority queue of your dreams. it's giving "data structures but make it cute." 🎀

✨ NAME ✨

globus_priority_q — Priority Queue.

yep. that's it. that's the whole name. Priority Queue. (the original page says it twice, so like… we're saying it twice too. it's iconic like that. 💅)

---

🌸 SYNOPSIS 🌸

🦋 Data Structures

• struct globus_priority_q_s — the Priority Queue Structure itself, the whole vibe container.

🎀 Typedefs

• typedef int(* globus_priority_q_cmp_func_t) (void *priority_1, void *priority_2) — the Priority Comparison Predicate, aka the little function that decides who's more important. 👑
• typedef struct globus_priority_q_s globus_priority_q_t — Priority Queue Structure, but as a typedef, because typing struct globus_priority_q_s every time is not the move.

⭐ Functions

• int globus_priority_q_init (globus_priority_q_t *priority_q, globus_priority_q_cmp_func_t cmp_func) — Initialize a priority queue.
• int globus_priority_q_destroy (globus_priority_q_t *priority_q) — Destroy a Priority Queue.
• globus_bool_t globus_priority_q_empty (globus_priority_q_t *priority_q) — Priority Queue Empty Predicate.
• int globus_priority_q_size (globus_priority_q_t *priority_q) — Priority Queue Size.
• int globus_priority_q_enqueue (globus_priority_q_t *priority_q, void *datum, void *priority) — Add a Datum to a Priority Queue.
• void * globus_priority_q_dequeue (globus_priority_q_t *priority_q) — Remove a Datum From A Priority Queue.
• void * globus_priority_q_first (globus_priority_q_t *priority_q) — Get the Highest-Priority Datum From a Priority Queue.
• void * globus_priority_q_first_priority (globus_priority_q_t *priority_q) — Get the Highest Priority in Priority Queue.
• void * globus_priority_q_remove (globus_priority_q_t *priority_q, void *datum) — Remove an Arbitrary Datum from a Priority Queue.
• void * globus_priority_q_modify (globus_priority_q_t *priority_q, void *datum, void *new_priority) — Modify the Priority of Datum.

---

🌈 Detailed Description 🌈

Priority Queue. 💖

so this module defines a priority queue for globus, and no cap, it's implemented using a binary heap (minheap). and here's the tea bestie — it does NOT have a fifo fallback for like priorities. not me finding out the hard way 😭

if you need fifo fallback, you should use a compound priority with the primary priority being the 'real' priority and the secondary being a serial number. periodt.

to use this priority queue type, define a comparison function of type globus_priority_q_cmp_func_t and pass that to globus_priority_q_init().

to add and remove items in priority order, use globus_priority_q_enqueue() and globus_priority_q_dequeue() respectively.

to remove a datum ignoring its priority, use globus_priority_q_remove().

to inspect the first element and its priority, use globus_priority_q_first() and globus_priority_q_first_priority() respectively.

to determine whether a queue is empty or the number of data in it, use globus_priority_q_empty() and globus_priority_q_size().

to modify the priority of a datum already in the queue, use globus_priority_q_modify().

when finished with the queue, use globus_priority_q_destroy() to free data associated with the priority queue. don't forget, bestie — that's a leak waiting to happen. 🙈

---

💜 Typedef Documentation 💜

🧚 typedef int(* globus_priority_q_cmp_func_t) (void *priority_1, void *priority_2)

Priority Comparison Predicate. this type is used to implement comparison of two priorities for inserting items into the priority queue. a function of this type is passed to globus_priority_q_init() to determine how priorities are computed in a newly created priority queue. it's literally the main character of the whole sorting situation. 👑

🌸 Parameters

• priority_1 — First priority to compare
• priority_2 — Second priority to compare

⭐ Return values

• > 0 — The priority of priority_1 is less than that of priority_2.
• < 0 — The priority of priority_1 is greater than that of priority_2.
• = 0 — The priorities of priority_1 and priority_2 are the same.

heads up: yes, the signs are flipped from what your brain expects. > 0 means "less than." read it twice. it's giving chaos but it's fine. 💀

🦋 typedef struct globus_priority_q_s globus_priority_q_t

Priority Queue Structure. a pointer to a structure of this type is passed to all functions in the Priority Queue module. it is not intended to be inspected or modified outside of this API — so hands off, bestie, that's private property. 🙅‍♀️

---

and there's more where that came from… 🫶

✨ FUNCTION DOCUMENTATION ✨

okay bestie, this is the part where we actually touch the functions. Every single one, no skipping, fr fr. 💖

void * globus_priority_q_dequeue (globus_priority_q_t * priority_q)

Remove a Datum From A Priority Queue. This one yanks the highest-priority datum out of the given priority queue and hands it to you. If priority_q is NULL, or the queue is empty, it just gives you NULL. no cap. 💅

Parameters:

• priority_q — Pointer to the priority queue to remove from.

Returns:

• This function returns the highest-priority datum from the priority queue.

---

int globus_priority_q_destroy (globus_priority_q_t * priority_q)

Destroy a Priority Queue. It destroys the contents of a priority queue. After this returns, the structure pointed to by priority_q is invalid and must not be passed to any functions in the Priority Queue module other than globus_priority_q_init(). periodt.

Note: this function does not call any destructors for the data inserted into the priority queue, so the caller must be sure to either have other references to those data or free them before calling this function. Don't skip that part. 😭

Parameters:

• priority_q — Pointer to the priority_q to destroy.

Return values:

• GLOBUS_SUCCESS — Success
• GLOBUS_FAILURE — Failure

---

globus_bool_t globus_priority_q_empty (globus_priority_q_t * priority_q)

Priority Queue Empty Predicate. Vibe check: is the given priority queue empty? It counts as empty if it has been initialized via globus_priority_q_init() and there are no items inserted via globus_priority_q_enqueue() that haven't been removed by calling globus_priority_q_remove() or globus_priority_q_dequeue(). If it's empty, this returns GLOBUS_TRUE; otherwise it returns GLOBUS_FALSE. 🫶

Parameters:

• priority_q — Pointer to the priority queue to check

Return values:

• GLOBUS_TRUE — The priority queue is empty
• GLOBUS_FALSE — The priority queue is not empty, or the priority queue is invalid

---

int globus_priority_q_enqueue (globus_priority_q_t * priority_q, void * datum, void * priority)

Add a Datum to a Priority Queue. Inserts a datum into the priority queue based on its priority. When an item is inserted, the pointers to both the datum and the priority are copied into the priority_q data structure, so neither may be freed until the datum is removed from the priority queue — otherwise, undefined behavior may occur. and we don't do undefined behavior in this house. 💀

Note: there is no fifo fallback for priorities, so the order of two items with equivalent priorities is not specified relative to each other. To enable fifo fallback, use a compound priority that includes a priority level and a sequence number as the value pointed to by the priority parameter, and pass a suitable comparison function to initialize the priority queue. that's the move. ✨

Parameters:

• priority_q — Pointer to the priority queue to insert datum into
• datum — The datum to insert into the queue
• priority — The priority of the datum

Return values:

• GLOBUS_SUCCESS — Success
• GLOBUS_FAILURE — Failure

---

void * globus_priority_q_first (globus_priority_q_t * priority_q)

Get the Highest-Priority Datum From a Priority Queue. Returns the highest-priority datum from the priority queue pointed to by priority_q. The datum is not removed from the queue; to do that, use globus_priority_q_dequeue() instead. If priority_q is NULL or the queue is empty, this function returns NULL. The priority queue retains a reference to the returned datum, so the pointer value returned must not be freed until the datum is removed from the queue. peek but don't yeet, bestie. 👑

Parameters:

• priority_q — Pointer to the priority queue to inspect

Returns:

• This function returns the highest-priority datum from the priority queue.

---

void * globus_priority_q_first_priority (globus_priority_q_t * priority_q)

Get the Highest Priority in Priority Queue. Returns the value of highest priority in the priority queue — not the datum associated with that priority. If priority_q is NULL or empty, this function returns NULL. The priority queue retains a reference to the returned priority, so the pointer value returned must not be freed until the datum associated with it is removed from the queue. it's giving priority-only energy. 💜

Parameters:

• priority_q — Pointer to the priority queue to inspect

Returns:

• This function returns the highest priority value in the priority queue.

---

int globus_priority_q_init (globus_priority_q_t * priority_q, globus_priority_q_cmp_func_t cmp_func)

Initialize a priority queue. This initializes a globus_priority_q_t structure for use with the other functions in the Priority Queue module. If this function returns GLOBUS_SUCCESS, the caller is responsible for deallocating the members of this structure when it is no longer needed by passing it to globus_priority_q_destroy(). you're the main character now, so act like it. 🌟

Parameters:

• priority_q — Pointer to the priority queue structure to initialize.
• cmp_func — Pointer to a function which computes the relative relationship between two priorities. See the documentation of globus_priority_q_cmp_func_t for details on how to implement that function.

Return values:

• GLOBUS_SUCCESS — Success
• GLOBUS_FAILURE — Failure

---

void * globus_priority_q_modify (globus_priority_q_t * priority_q, void * datum, void * new_priority)

Modify the Priority of Datum. Changes the priority of the highest-priority instance of datum in the priority queue so that it becomes new_priority. The old priority of the datum is returned. If priority_q is NULL or datum is not present, this function returns NULL. glow-up but for priorities. 💅

Parameters:

• priority_q — Pointer to the priority queue to modify
• datum — Pointer to the datum whose priority is being modified
• new_priority — Pointer to the new priority

Returns:

• This function returns the old priority of datum.

---

void * globus_priority_q_remove (globus_priority_q_t * priority_q, void * datum)

Remove an Arbitrary Datum from a Priority Queue. Removes the highest-priority instance of the specified datum from the priority queue and returns the datum if it is found. If priority_q is NULL or the datum is not found, this function returns NULL. not me removing a specific datum instead of the top one, iconic. 🎀

Parameters:

• priority_q — Pointer to the priority queue to modify
• datum — Pointer to the datum to search for.

Returns:

• This function returns datum if it was present in the priority queue

---

int globus_priority_q_size (globus_priority_q_t * priority_q)

Priority Queue Size. Returns the size of the priority queue, that is, the number of elements that are currently enqueued in it. The special value GLOBUS_FAILURE is returned if a null pointer is passed to this function. how many? this many. 🔥

Parameters:

• priority_q — Pointer to the priority queue to check

Returns:

• This function returns the number of elements in the queue, or GLOBUS_FAILURE if the priority_q pointer is invalid.

---

👑 AUTHOR 👑

Generated automatically by Doxygen for globus_common from the source code. slay. ✨

---

mwah 💋 — from globus_common, Version 18.15, page globus_priority_q(3). (The footer didn't include a date, so that's the source/version and page, bestie.) 💖