/*
 * Copyright (c) 2020 Red Hat, Inc.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA. 
 *
 * $Id: //eng/uds-releases/jasper/src/uds/util/eventCount.h#1 $
 */

#ifndef EVENT_COUNT_H
#define EVENT_COUNT_H

#include "timeUtils.h"
#include "typeDefs.h"

/**
 * An EventCount is a lock-free equivalent of a condition variable.
 *
 * Using an EventCount, a lock-free producer/consumer can wait for a state
 * change (adding an item to an empty queue, for example) without spinning or
 * falling back on the use of mutex-based locks. Signalling is cheap when
 * there are no waiters (a memory fence), and preparing to wait is
 * also inexpensive (an atomic add instruction).
 *
 * A lock-free producer should call eventCountBroadcast() after any mutation
 * to the lock-free data structure that a consumer might be waiting on. The
 * consumers should poll for work like this:
 *
 *   for (;;) {
 *     // Fast path--no additional cost to consumer.
 *     if (lockFreeDequeue(&item)) {
 *       return item;
 *     }
 *     // Two-step wait: get current token and poll state, either cancelling
 *     // the wait or waiting for the token to be signalled.
 *     EventToken token = eventCountPrepare(ec);
 *     if (lockFreeDequeue(&item)) {
 *       eventCountCancel(ec, token);
 *       return item;
 *     }
 *     eventCountWait(ec, token, NULL);
 *     // State has changed, but must check condition again, so loop.
 *   }
 *
 * Once eventCountPrepare() is called, the caller should neither dally, sleep,
 * nor perform long-running or blocking actions before passing the token to
 * eventCountCancel() or eventCountWait(). The implementation is optimized for
 * a short polling window, and will not perform well if there are outstanding
 * tokens that have been signalled but not waited upon.
 **/

typedef struct eventCount EventCount;

typedef unsigned int EventToken;

/**
 * Allocate and initialize an EventCount.
 *
 * @param ecPtr  a pointer to hold the new EventCount
 **/
__attribute__((warn_unused_result))
int makeEventCount(EventCount **ecPtr);

/**
 * Free an EventCount. It must no longer be in use.
 *
 * @param ec  the EventCount to free
 **/
void freeEventCount(EventCount *ec);

/**
 * Wake all threads that are waiting for the next event.
 *
 * @param ec  the EventCount to signal
 **/
void eventCountBroadcast(EventCount *ec);

/**
 * Prepare to wait for the EventCount to change by capturing a token of its
 * current state. The caller MUST eventually either call eventCountWait() or
 * eventCountCancel() exactly once for each token obtained.
 *
 * @param ec  the EventCount on which to prepare to wait
 *
 * @return an EventToken to be passed to the next eventCountWait() call
 **/
EventToken eventCountPrepare(EventCount *ec)
  __attribute__((warn_unused_result));

/**
 * Cancel a wait token that has been prepared but not waited upon. This must
 * be called after eventCountPrepare() when eventCountWait() is not going to
 * be invoked on the token.
 *
 * @param ec     the EventCount from which a wait token was obtained
 * @param token  the wait token that will never be passed to eventCountWait()
 **/
void eventCountCancel(EventCount *ec, EventToken token);

/**
 * Check if the current event count state corresponds to the provided token,
 * and if it is, wait for a signal that the state has changed. If an optional
 * timeout is provided, the wait will terminate after the timeout has elapsed.
 * Timing out automatically cancels the wait token, so callers must not
 * attempt to cancel the token on timeout.
 *
 * @param ec       the EventCount on which to wait
 * @param token    the EventToken returned by eventCountPrepare()
 * @param timeout  either NULL or a relative timeout for the wait operation
 *
 * @return true if the state has already changed or if signalled, otherwise
 *         false if a timeout was provided and the wait timed out
 **/
bool eventCountWait(EventCount *ec, EventToken token, const RelTime *timeout);

#endif /* EVENT_COUNT_H */