Program Listing for File cmb_priorityqueue.h

↰ Return to documentation for file (include/cmb_priorityqueue.h)

/*
 * Copyright (c) Asbjørn M. Bonvik 2026.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef CIMBA_CMB_PRIORITYQUEUE_H
#define CIMBA_CMB_PRIORITYQUEUE_H

#include <stdint.h>

#include "cmb_assert.h"
#include "cmb_resourceguard.h"
#include "cmb_timeseries.h"

#include "cmi_hashheap.h"
#include "cmi_resourcebase.h"

struct cmb_priorityqueue {
    struct cmi_resourcebase core;
    struct cmb_resourceguard front_guard;
    struct cmb_resourceguard rear_guard;
    struct cmi_hashheap queue;
    uint64_t capacity;
    bool is_recording;
    struct cmb_timeseries history;
};

extern struct cmb_priorityqueue *cmb_priorityqueue_create(void);

extern void cmb_priorityqueue_initialize(struct cmb_priorityqueue *pqp,
                                         const char *name,
                                         uint64_t capacity);

extern void cmb_priorityqueue_terminate(struct cmb_priorityqueue *pqp);

extern void cmb_priorityqueue_destroy(struct cmb_priorityqueue *pqp);

extern int64_t cmb_priorityqueue_get(struct cmb_priorityqueue *pqp,
                                     void **objectloc);

extern int64_t cmb_priorityqueue_put(struct cmb_priorityqueue *pqp,
                                     void *object,
                                     int64_t priority,
                                     uint64_t *handleloc);

extern uint64_t cmb_priorityqueue_position(struct cmb_priorityqueue *pqp,
                                           uint64_t handle);

[[maybe_unused]]
static inline bool cmb_priorityqueue_cancel(struct cmb_priorityqueue *pqp,
                                            const uint64_t handle)
{
    cmb_assert_release(pqp != NULL);

    struct cmi_hashheap *hp = &(pqp->queue);
    const bool found = cmi_hashheap_remove(hp, handle);

    return found;
}

[[maybe_unused]]
static inline void cmb_priorityqueue_reprioritize(struct cmb_priorityqueue *pqp,
                                                  const uint64_t handle,
                                                  const int64_t priority)
{
    cmb_assert_release(pqp != NULL);

    struct cmi_hashheap *hp = &(pqp->queue);
    cmi_hashheap_reprioritize(hp, handle, 0.0, priority);
}

[[maybe_unused]]
static inline const char *cmb_priorityqueue_name(struct cmb_priorityqueue *pqp)
{
    cmb_assert_debug(pqp != NULL);

    const struct cmi_resourcebase *rbp = (struct cmi_resourcebase *)pqp;
    cmb_assert_release(rbp->cookie == CMI_INITIALIZED);

    return rbp->name;
}

[[maybe_unused]]
static inline uint64_t cmb_priorityqueue_length(struct cmb_priorityqueue *pqp)
{
    cmb_assert_debug(pqp != NULL);
    cmb_assert_release(((struct cmi_resourcebase *)pqp)->cookie == CMI_INITIALIZED);

    return pqp->queue.heap_count;
}

[[maybe_unused]]
static inline uint64_t cmb_priorityqueue_space(struct cmb_priorityqueue *pqp)
{
    cmb_assert_release(pqp != NULL);
    cmb_assert_release(((struct cmi_resourcebase *)pqp)->cookie == CMI_INITIALIZED);
    cmb_assert_debug(pqp->queue.heap_count <= pqp->capacity);

    return (pqp->capacity - pqp->queue.heap_count);
}

extern void cmb_priorityqueue_recording_start(struct cmb_priorityqueue *pqp);

extern void cmb_priorityqueue_recording_stop(struct cmb_priorityqueue *pqp);

extern struct cmb_timeseries *cmb_priorityqueue_history(struct cmb_priorityqueue *pqp);

extern void cmb_priorityqueue_report_print(struct cmb_priorityqueue *pqp, FILE *fp);

#endif /* CIMBA_CMB_PRIORITYQUEUE_H */