/*
 * (c) Copyright, Real-Time Innovations, 2025.
 * All rights reserved.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef reda_stickyCounter_h
#define reda_stickyCounter_h

#include "osapi/osapi_type.h"
#include "reda/reda_dll.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief A counter that can only be increased or decreased if it is not zero.
 *
 * This counter can be increased and decreased as many times as needed, but
 * once it reaches zero, it cannot be increased nor decreased anymore.
 * This is really useful to keep track of the number of threads that are using
 * a shared resource, and to know when the resource can be safely deleted.
 *
 * The implementation is thread-safe and even more, wait-free. This means that
 * the operations are guaranteed to finish in a finite number of steps, no
 * matter how many threads are using the counter. Of course, no mutexes are
 * required.
 */
struct REDAStickyCounter;

/**
 * @brief Initialize a REDAStickyCounter object.
 * The initial value of the counter is 1 (it can't be zero, otherwise it would
 * be useless).
 */
extern REDADllExport void REDAStickyCounter_initialize(
        struct REDAStickyCounter *self);

/**
 * @brief Get the current value of the counter.
 */
extern REDADllExport RTI_UINT64
REDAStickyCounter_get(struct REDAStickyCounter *self);

/**
 * @brief Increase the value of the counter only if it is not zero.
 * @return RTI_TRUE if the counter was increased, RTI_FALSE if the counter
 * was zero.
 */
extern REDADllExport RTIBool
REDAStickyCounter_increase(struct REDAStickyCounter *self);

/**
 * @brief Decrease the value of the counter only if it is not zero.
 * @return RTI_TRUE if the counter is already zero, RTI_FALSE otherwise.
 */
extern REDADllExport RTIBool
REDAStickyCounter_decrease(struct REDAStickyCounter *self);

#ifdef __cplusplus
} /* extern "C" */
#endif

#include "reda/reda_stickyCounter_impl.h"

#endif /* reda_stickyCounter_h */