conflict-set/include/ConflictSet.h

/*
Copyright 2024 Andrew Noyes

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.
*/

#pragma once

#include <stdint.h>

#ifdef __cplusplus
namespace weaselab {
/** A data structure for optimistic concurrency control on ranges of
 * bitwise-lexicographically-ordered keys. All versions must be >= 0.
 *
 * Thread safety:
 *   - It's safe to operate on two different ConflictSets in two different
 * threads concurrently
 *   - It's safe to have multiple threads operating on the same ConflictSet
 * concurrently if and only if all threads only call const methods
 */
struct __attribute__((__visibility__("default"))) ConflictSet {
  enum Result {
    /** The result of a check which does not intersect any conflicting writes */
    Commit,
    /** The result of a check which intersects a write at a version >
       readVersion */
    Conflict,
    /** The result of a check with a readVersion older than the highest call to
       `setOldestVersion` */
    TooOld
  };

  /** Bytes ordered lexicographically */
  struct Key {
    const uint8_t *p;
    int len;
  };

  /** Denotes a set of keys to be checked for conflicting writes since
   * `readVersion` */
  struct ReadRange {
    Key begin;
    /** `end` having length 0 denotes that this range is the single key {begin}.
     * Otherwise this denotes the range [begin, end), and begin must be < end */
    Key end;
    /** `readVersion` older than the the oldestVersion or the version of the
     * latest call to `addWrites` minus two billion will result in `TooOld` */
    int64_t readVersion;
  };

  /** Denotes a set of keys to be written at `writeVersion` */
  struct WriteRange {
    Key begin;
    /** `end` having length 0 denotes that this range is the single key {begin}.
     * Otherwise this denotes the range [begin, end), and begin must be < end */
    Key end;
  };

  /** The result of checking reads[i] is written in results[i] */
  void check(const ReadRange *reads, Result *results, int count) const;

  /** Reads intersecting writes where readVersion < `writeVersion` will result
   * in `Conflict` (or `TooOld`, eventually).  `writeVersion` must be greater
   * than or equal to all previous write versions. */
  void addWrites(const WriteRange *writes, int count, int64_t writeVersion);

  /** Reads where readVersion < oldestVersion will result in `TooOld`. Must be
   * greater than or equal to all previous oldest versions. */
  void setOldestVersion(int64_t oldestVersion);

  /** Reads where readVersion < oldestVersion will result in `TooOld`. There are
   * no writes initially */
  explicit ConflictSet(int64_t oldestVersion);

  ~ConflictSet();

  /** Returns the total bytes in use by this ConflictSet */
  int64_t getBytes() const;

  /** Experimental! */
  struct MetricsV1 {
    /** A null-terminated string with static lifetime. Matches the regex
     * [a-zA-Z_:][a-zA-Z0-9_:]*
     */
    const char *name;
    /** A null-terminated string with static lifetime.  May contain any sequence
     * of UTF-8 characters (after the metric name), but the backslash and the
     * line feed characters have to be escaped as \\ and \n, respectively.
     */
    const char *help;
    /** Counters are >= 0 and non-decreasing. Gauges are any value. */
    enum Type { Counter, Gauge } type;
    /** Thread-safety: do not read concurrently with a call to any non-const
     * method in the ConflictSet associated with this metric. */
    const double *value;
  };

  /** Experimental! Store a pointer to an array of MetricsV1 (owned by the
   * ConflictSet) to `*metrics`, and its length to `*count`. This function makes
   * no guarantees about the contents of the metrics (e.g. names, help text, and
   * the meaning of values). A correct implementation is free to return nonsense
   * or nothing at all. Not intended to be inspected programmatically. Only
   * intended to be plumbed along to e.g. Prometheus. */
  void getMetricsV1(MetricsV1 **metrics, int *count) const;

#if __cplusplus > 199711L
  ConflictSet(ConflictSet &&) noexcept;
  ConflictSet &operator=(ConflictSet &&) noexcept;
  ConflictSet(const ConflictSet &) = delete;
  ConflictSet &operator=(const ConflictSet &) = delete;
#endif

  /** @private */
  struct Impl;

private:
  Impl *impl;
};
} /* namespace weaselab */

#else

/** A data structure for optimistic concurrency control on ranges of
 * bitwise-lexicographically-ordered keys. All versions must be >= 0.
 *
 * Thread safety:
 *   - It's safe to operate on two different ConflictSets in two different
 * threads concurrently
 *   - It's safe to have multiple threads operating on the same ConflictSet
 * concurrently if and only if all threads only call functions that accept a
 * const ConflictSet pointer
 */
typedef struct ConflictSet ConflictSet;

typedef enum {
  /** The result of a check which does not intersect any conflicting writes */
  ConflictSet_Commit,
  /** The result of a check which intersects a write at a version > readVersion
   */
  ConflictSet_Conflict,
  /** The result of a check with a readVersion older than the highest call to
     `setOldestVersion` */
  ConflictSet_TooOld
} ConflictSet_Result;

/** Bytes ordered lexicographically */
typedef struct {
  const uint8_t *p;
  int len;
} ConflictSet_Key;

/** Denotes a set of keys to be checked for conflicting writes since
 * `readVersion` */
typedef struct {
  ConflictSet_Key begin;
  /** `end` having length 0 denotes that this range is the single key {begin}.
   * Otherwise this denotes the range [begin, end), and begin must be < end */
  ConflictSet_Key end;
  /** `readVersion` older than the the oldestVersion or the version of the
   * latest call to `addWrites` minus two billion will result in `TooOld` */
  int64_t readVersion;
} ConflictSet_ReadRange;

/** Denotes a set of keys to be written at `writeVersion` */
typedef struct {
  ConflictSet_Key begin;
  /** `end` having length 0 denotes that this range is the single key {begin}.
   * Otherwise this denotes the range [begin, end), and begin must be < end */
  ConflictSet_Key end;
} ConflictSet_WriteRange;

/** The result of checking reads[i] is written in results[i] */
void ConflictSet_check(const ConflictSet *cs,
                       const ConflictSet_ReadRange *reads,
                       ConflictSet_Result *results, int count);

/** Reads intersecting writes where readVersion < `writeVersion` will result in
 * `Conflict` (or `TooOld`, eventually).  `writeVersion` must be greater than or
 * equal to all previous write versions.  */
void ConflictSet_addWrites(ConflictSet *cs,
                           const ConflictSet_WriteRange *writes, int count,
                           int64_t writeVersion);

/** Reads where readVersion < oldestVersion will result in `TooOld`. Must be
 * greater than or equal to all previous oldest versions. */
void ConflictSet_setOldestVersion(ConflictSet *cs, int64_t oldestVersion);

/** Reads where readVersion < oldestVersion will result in `TooOld`. There are
 * no writes initially */
ConflictSet *ConflictSet_create(int64_t oldestVersion);

void ConflictSet_destroy(ConflictSet *cs);

/** Returns the total bytes in use by this ConflictSet */
int64_t ConflictSet_getBytes(const ConflictSet *cs);

#endif