<commit_before>/* vi: set ts=4 expandtab shiftwidth=4: */
#ifndef _H_COM_DIAG_DIMINUTO_READERWRITER_
#define _H_COM_DIAG_DIMINUTO_READERWRITER_

/**
 * @file
 * @copyright Copyright 2020 Digital Aggregates Corporation, Colorado, USA.
 * @note Licensed under the terms in LICENSE.txt.
 * @brief
 * @author <NAME> <mailto:<EMAIL>>
 * @see Diminuto <https://github.com/coverclock/com-diag-diminuto>
 * @details
 * Reader Writer is an implementation of a synchronization mechanism for
 * the classic Reader-Writer (a.k.a."Readers-Writers") problem. This
 * version not only treats readers and writers fairly, preventing starvation
 * of either role, but preserves the relative order of the reader and writer
 * requests. The order is preserved independently of whether the underlying
 * implementation of condition variables implements a FIFO queue, or what the
 * priorities of the calling threads may be.
 *
 * Although I've made some effort to make this work correctly in the face
 * of thread cancellation, I haven't tested that scenario (and probably
 * won't). Diminuto Threads specifically disable cancellation, although
 * Reader Writer doesn't depend upon Diminuto Threads.
 *
 * Still considered somewhat experimental since I don't believe I have
 * tested it completely adequately.
 *
 * REFERENCES
 *
 * <NAME>, <NAME>, <NAME>, "Concurrent Control with ''Readers''
 * and ''Writers''", CACM, 14.10, 1971-10
 *
 * <NAME>, "Monitors: An Operating System Structuring Concept", CACM,
 * 17.10, 1974-10
 *
 * <NAME>, "Time, Clocks, and the Ordering of Events in a Distributed
 * System", CACM, 21.7, 1978-07
 *
 * <NAME>, <NAME>, "Experience with Processes and Monitors in Mesa",
 * CACM, 23.2, 1980-02
 *
 * <NAME>, "The third readers-writers problem", rfc1149.net, 2011-11-07
 *
 * <NAME>, <NAME>, "Faster Fair Solution for the Reader-Writer Problem",
 * 2013
 *
 * pthread_cond_broadcast, pthead_cond_signal, Open Group Base Specification
 * Issue 7, 2018 edition, IEEE Std. 1003.1-2017, 2018
 *
 * pthread_cond_timedwait, pthead_cond_wait, Open Group Base Specification
 * Issue 7, 2018 edition, IEEE Std. 1003.1-2017, 2018
 *
 * Wikipedia, "Readers-writers problem", 2020-11-23
 *
 * <NAME>, "First-Come First-Served Readers and Writers in C using
 * Condition Variables", 2020-12
 */

/*******************************************************************************
 * PREREQUISITES
 ******************************************************************************/

#include "com/diag/diminuto/diminuto_widthof.h"
#include "com/diag/diminuto/diminuto_ring.h"
#include <errno.h>
#include <stdint.h>
#include <pthread.h>
#include <stdio.h>

/*******************************************************************************
 * CONSTANTS
 ******************************************************************************/

/**
 * These are the error codes that Reader Writer might return itself, in
 * addition to those error codes that the underlying platform (like POSIX
 * threads) might generate. The FULL error code is an application error, while
 * ERROR and UNEXPECTED are probably indicitive of bugs in Reader Writer.
 */
enum DiminutoReaderWriterError {
    DIMINUTO_READERWRITER_ERROR         = EIO,      /**< Unspecified error. */<commit_msg>[1] Typo. BUILDS<commit_after>/* vi: set ts=4 expandtab shiftwidth=4: */
#ifndef _H_COM_DIAG_DIMINUTO_READERWRITER_
#define _H_COM_DIAG_DIMINUTO_READERWRITER_

/**
 * @file
 * @copyright Copyright 2020 Digital Aggregates Corporation, Colorado, USA.
 * @note Licensed under the terms in LICENSE.txt.
 * @brief
 * @author <NAME> <mailto:<EMAIL>>
 * @see Diminuto <https://github.com/coverclock/com-diag-diminuto>
 * @details
 * Reader Writer is an implementation of a synchronization mechanism for
 * the classic Reader-Writer (a.k.a."Readers-Writers") problem. This
 * version not only treats readers and writers fairly, preventing starvation
 * of either role, but preserves the relative order of the reader and writer
 * requests. The order is preserved independently of whether the underlying
 * implementation of condition variables implements a FIFO queue, or what the
 * priorities of the calling threads may be.
 *
 * Although I've made some effort to make this work correctly in the face
 * of thread cancellation, I haven't tested that scenario (and probably
 * won't). Diminuto Threads specifically disable cancellation, although
 * Reader Writer doesn't depend upon Diminuto Threads.
 *
 * Still considered somewhat experimental since I don't believe I have
 * tested it completely adequately.
 *
 * REFERENCES
 *
 * <NAME>, <NAME>, <NAME>, "Concurrent Control with ''Readers''
 * and ''Writers''", CACM, 14.10, 1971-10
 *
 * <NAME>, "Monitors: An Operating System Structuring Concept", CACM,
 * 17.10, 1974-10
 *
 * <NAME>, "Time, Clocks, and the Ordering of Events in a Distributed
 * System", CACM, 21.7, 1978-07
 *
 * <NAME>, <NAME>, "Experience with Processes and Monitors in Mesa",
 * CACM, 23.2, 1980-02
 *
 * <NAME>, "The third readers-writers problem", rfc1149.net, 2011-11-07
 *
 * <NAME>, <NAME>, "Faster Fair Solution for the Reader-Writer Problem",
 * 2013
 *
 * pthread_cond_broadcast, pthead_cond_signal, Open Group Base Specification
 * Issue 7, 2018 edition, IEEE Std. 1003.1-2017, 2018
 *
 * pthread_cond_timedwait, pthead_cond_wait, Open Group Base Specification
 * Issue 7, 2018 edition, IEEE Std. 1003.1-2017, 2018
 *
 * Wikipedia, "Readers-writers problem", 2020-11-23
 *
 * <NAME>, "First-Come First-Served Readers and Writers in C using
 * Monitors", 2020-12
 */

/*******************************************************************************
 * PREREQUISITES
 ******************************************************************************/

#include "com/diag/diminuto/diminuto_widthof.h"
#include "com/diag/diminuto/diminuto_ring.h"
#include <errno.h>
#include <stdint.h>
#include <pthread.h>
#include <stdio.h>

/*******************************************************************************
 * CONSTANTS
 ******************************************************************************/

/**
 * These are the error codes that Reader Writer might return itself, in
 * addition to those error codes that the underlying platform (like POSIX
 * threads) might generate. The FULL error code is an application error, while
 * ERROR and UNEXPECTED are probably indicitive of bugs in Reader Writer.
 */
enum DiminutoReaderWriterError {
    DIMINUTO_READERWRITER_ERROR         = EIO,      /**< Unspecified error. */
{'fraction_non_alphanumeric': 0.1894429055093875, 'fraction_numerical': 0.0340104647583872, 'mean_word_length': 4.828699551569507, 'pattern_counts': {'":': 0, '<': 43, '<?xml version=': 0, '>': 41, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3745372', 'n_tokens_mistral': 2066, 'n_tokens_neox': 1795, 'n_words': 659}