include/tsutil/TsSharedMutex.h

/** @file

  A drop-in replacement for std::shared_mutex with guarantees against writer
  starvation.

  @section license License

  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you 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 <cstdio>
#include <cstdlib>
#include <pthread.h>
#include "tsutil/Strerror.h"
#include "tsutil/Assert.h"
#include "tsutil/ts_thread_safety.h"

#ifdef X
#error "X preprocessor symbol defined"
#endif

#if !defined(__OPTIMIZE__)

#define X(P) P

#include <atomic>

#else

#define X(P)

#endif

namespace ts
{
// A class with the same interface as std::shared_mutex, but which is not prone to writer starvation.
//
class TS_CAPABILITY("shared_mutex") shared_mutex
{
public:
  shared_mutex() {}

  // No copying or moving.
  //
  shared_mutex(shared_mutex const &)            = delete;
  shared_mutex &operator=(shared_mutex const &) = delete;

  // The lock/unlock methods are the trusted implementation of this capability:
  // their bodies drive the raw pthread_rwlock_t, which some libc headers (e.g.
  // FreeBSD's <pthread.h>) annotate as a capability in its own right. Exempt the
  // bodies from analysis so only the capability contract on each signature is
  // checked; the actual data-race checking happens at the call sites.
  void
  lock() TS_ACQUIRE() TS_NO_THREAD_SAFETY_ANALYSIS
  {
    int error = pthread_rwlock_wrlock(&_lock);
    if (error != 0) {
      _call_fatal("pthread_rwlock_wrlock", &_lock, error);
    }
    X(_exclusive = true;)
  }

  bool
  try_lock() TS_TRY_ACQUIRE(true) TS_NO_THREAD_SAFETY_ANALYSIS
  {
    int error = pthread_rwlock_trywrlock(&_lock);
    if (EBUSY == error) {
      return false;
    }
    if (error != 0) {
      _call_fatal("pthread_rwlock_trywrlock", &_lock, error);
    }
    X(_exclusive = true;)

    return true;
  }

  void
  unlock() TS_RELEASE() TS_NO_THREAD_SAFETY_ANALYSIS
  {
    X(debug_assert(_exclusive);)
    X(_exclusive = false;)

    _unlock();
  }

  void
  lock_shared() TS_ACQUIRE_SHARED() TS_NO_THREAD_SAFETY_ANALYSIS
  {
    int error = pthread_rwlock_rdlock(&_lock);
    if (error != 0) {
      _call_fatal("pthread_rwlock_rdlock", &_lock, error);
    }
    X(debug_assert(_shared >= 0);)
    X(++_shared;)
    X(debug_assert(_shared > 0);)
  }

  bool
  try_lock_shared() TS_TRY_ACQUIRE_SHARED(true) TS_NO_THREAD_SAFETY_ANALYSIS
  {
    int error = pthread_rwlock_tryrdlock(&_lock);
    if (EBUSY == error) {
      return false;
    }
    if (error != 0) {
      _call_fatal("pthread_rwlock_tryrdlock", &_lock, error);
    }

    X(++_shared;)

    return true;
  }

  void
  unlock_shared() TS_RELEASE_SHARED() TS_NO_THREAD_SAFETY_ANALYSIS
  {
    X(debug_assert(_shared > 0);)
    X(--_shared;)
    X(debug_assert(_shared >= 0);)

    _unlock();
  }

  ~shared_mutex()
  {
    int error = pthread_rwlock_destroy(&_lock);
    if (error != 0) {
      _call_fatal("pthread_rwlock_destroy", &_lock, error);
    }
  }

  using native_handle_type = pthread_rwlock_t;

  native_handle_type
  native_handle()
  {
    return _lock;
  }

private:
  void
  _unlock() TS_NO_THREAD_SAFETY_ANALYSIS
  {
    int error = pthread_rwlock_unlock(&_lock);
    if (error != 0) {
      _call_fatal("pthread_rwlock_unlock", &_lock, error);
    }
  }

#if defined(__linux__)
  // Use the initializer that prevents writer starvation.
  //
  pthread_rwlock_t _lock = PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP;
#else
  // Testing indicates that for MacOS/Darwin and FreeBSD, pthread rwlocks always prevent writer starvation.
  //
  pthread_rwlock_t _lock = PTHREAD_RWLOCK_INITIALIZER;
#endif

  [[noreturn]] static void
  _call_fatal(char const *func_name, void *ptr, int errnum) noexcept
  try {
    fatal_error("{}({}) failed: {} ({})", func_name, ptr, Strerror(errnum).c_str(), errnum);
  } catch (...) {
    // Formatting the message can throw (it allocates); abort with a minimal
    // breadcrumb rather than let an exception escape into a noexcept destructor.
    fprintf(stderr, "shared_mutex: %s failed (%d); abort message formatting threw\n", func_name, errnum);
    std::abort();
  }

  // In debug builds, make sure shared vs. exclusive locks and unlocks are properly paired.
  //
  X(std::atomic<bool> _exclusive{false};)
  X(std::atomic<int> _shared{0};)
};

// RAII guards for ts::shared_mutex that carry Clang thread-safety capability
// state. Prefer these over std::unique_lock / std::shared_lock in code annotated
// for -Wthread-safety: the analysis does not reliably track the std wrappers
// (see tsutil/ts_thread_safety.h).
//
class TS_SCOPED_CAPABILITY write_guard
{
public:
  explicit write_guard(shared_mutex &m) TS_ACQUIRE(m) : _m(m) { _m.lock(); }
  ~write_guard() TS_RELEASE() { _m.unlock(); }

  write_guard(write_guard const &)            = delete;
  write_guard &operator=(write_guard const &) = delete;

private:
  shared_mutex &_m;
};

class TS_SCOPED_CAPABILITY read_guard
{
public:
  explicit read_guard(shared_mutex &m) TS_ACQUIRE_SHARED(m) : _m(m) { _m.lock_shared(); }
  // A scoped-capability destructor uses the plain release form even for a shared acquire.
  ~read_guard() TS_RELEASE() { _m.unlock_shared(); }

  read_guard(read_guard const &)            = delete;
  read_guard &operator=(read_guard const &) = delete;

private:
  shared_mutex &_m;
};

} // end namespace ts

#undef X