/* Copyright 2016 Google Inc.

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

/* This package provides a mutex nsync_mu and a Mesa-style condition variable nsync_cv. */

#include "nsync_cpp.h"

#include "platform.h"

#include "compiler.h"

#include "cputype.h"

#include "nsync.h"

#include "atomic.h"

#include "sem.h"

#include "dll.h"

#include "wait_internal.h"

#include "common.h"

NSYNC_CPP_START_

/* Implementation notes

   The implementations of nsync_mu and nsync_cv both use spinlocks to protect

   their waiter queues.  The spinlocks are implemented with atomic operations

   and a delay loop found below.  They could use pthread_mutex_t, but I wished

   to have an implementation independent of pthread mutexes and condition

   variables.

   nsync_mu and nsync_cv use the same type of doubly-linked list of waiters

   (see waiter.c).  This allows waiters to be transferred from the cv queue to

   the mu queue when a thread is logically woken from the cv but would

   immediately go to sleep on the mu.  See the wake_waiters() call.

   In mu, the "designated waker" is a thread that was waiting on mu, has been

   woken up, but as yet has neither acquired nor gone back to waiting.  The

   presence of such a thread is indicated by the MU_DESIG_WAKER bit in the mu

   word.  This bit allows the nsync_mu_unlock() code to avoid waking a second

   waiter when there's already one that will wake the next thread when the time

   comes.  This speeds things up when the lock is heavily contended, and the

   critical sections are small.

   The weasel words "with high probability" in the specification of

   nsync_mu_trylock() and nsync_mu_rtrylock() prevent clients from believing

   that they can determine with certainty whether another thread has given up a

   lock yet.  This, together with the requirement that a thread that acquired a

   mutex must release it (rather than it being released by another thread),

   prohibits clients from using mu as a sort of semaphore.  The intent is that

   it be used only for traditional mutual exclusion, and that clients that need

   a semaphore should use one.  This leaves room for certain future

   optimizations, and make it easier to apply detection of potential races via

   candidate lock-set algorithms, should that ever be desired.

   The nsync_mu_wait_with_deadline() and nsync_mu_wait_with_deadline() calls use an

   absolute rather than a relative timeout.  This is less error prone, as

   described in the comment on nsync_cv_wait_with_deadline().  Alas, relative

   timeouts are seductive in trivial examples (such as tests).  These are the

   first things that people try, so they are likely to be requested.  If enough

   people complain we could give them that particular piece of rope.

   Excessive evaluations of the same wait condition are avoided by maintaining

   waiter.same_condition as a doubly-linked list of waiters with the same

   non-NULL wait condition that are also adjacent in the waiter list.  This does

   well even with large numbers of threads if there is at most one

   wait condition that can be false at any given time (such as in a

   producer/consumer queue, which cannot be both empty and full

   simultaneously).  One could imagine a queueing mechanism that would

   guarantee to evaluate each condition at most once per wakeup, but that would

   be substantially more complex, and would still degrade if the number of

   distinct wakeup conditions were high.  So clients are advised to resort to

   condition variables if they have many distinct wakeup conditions. */

/* Used in spinloops to delay resumption of the loop.

   Usage:

       unsigned attempts = 0;

       while (try_something) {

    attempts = nsync_spin_delay_ (attempts);

       } */

unsigned nsync_spin_delay_ (unsigned attempts) {

  if (attempts < 7) {

    volatile int i;

    for (i = 0; i != 1 << attempts; i++) {

    }

    attempts++;

  } else {

    nsync_yield_ ();

  }

  return (attempts);

}

/* Spin until (*w & test) == 0, then atomically perform *w = ((*w | set) &

   ~clear), perform an acquire barrier, and return the previous value of *w.

   */

uint32_t nsync_spin_test_and_set_ (nsync_atomic_uint32_ *w, uint32_t test,

           uint32_t set, uint32_t clear) {

  unsigned attempts = 0; /* CV_SPINLOCK retry count */

  uint32_t old = ATM_LOAD (w);

  while ((old & test) != 0 || !ATM_CAS_ACQ (w, old, (old | set) & ~clear)) {

    attempts = nsync_spin_delay_ (attempts);

    old = ATM_LOAD (w);

  }

  return (old);

}

/* ====================================================================================== */

struct nsync_waiter_s *nsync_dll_nsync_waiter_ (nsync_dll_element_ *e) {

  struct nsync_waiter_s *nw = (struct nsync_waiter_s *) e->container;

  ASSERT (nw->tag == NSYNC_WAITER_TAG);

  ASSERT (e == &nw->q);

  return (nw);

}

waiter *nsync_dll_waiter_ (nsync_dll_element_ *e) {

  struct nsync_waiter_s *nw = DLL_NSYNC_WAITER (e);

  waiter *w = CONTAINER (waiter, nw, nw);

  ASSERT ((nw->flags & NSYNC_WAITER_FLAG_MUCV) != 0);

  ASSERT (w->tag == WAITER_TAG);

  ASSERT (e == &w->nw.q);

  return (w);

}

waiter *nsync_dll_waiter_samecond_ (nsync_dll_element_ *e) {

  waiter *w = (waiter *) e->container;

  ASSERT (w->tag == WAITER_TAG);

  ASSERT (e == &w->same_condition);

  return (w);

}

/* -------------------------------- */

static nsync_dll_list_ free_waiters = NULL;

/* free_waiters points to a doubly-linked list of free waiter structs. */

static nsync_atomic_uint32_ free_waiters_mu; /* spinlock; protects free_waiters */

static THREAD_LOCAL waiter *waiter_for_thread;

static void waiter_destroy (void *v) {

  waiter *w = (waiter *) v;

  /* Reset waiter_for_thread in case another thread-local variable reuses

     the waiter in its destructor while the waiter is taken by the other

     thread from free_waiters. This can happen as the destruction order

     of thread-local variables can be arbitrary in some platform e.g.

     POSIX.  */

  waiter_for_thread = NULL;

  IGNORE_RACES_START ();

  ASSERT ((w->flags & (WAITER_RESERVED|WAITER_IN_USE)) == WAITER_RESERVED);

  w->flags &= ~WAITER_RESERVED;

  nsync_spin_test_and_set_ (&free_waiters_mu, 1, 1, 0);

  free_waiters = nsync_dll_make_first_in_list_ (free_waiters, &w->nw.q);

  ATM_STORE_REL (&free_waiters_mu, 0); /* release store */

  IGNORE_RACES_END ();

}

/* If non-nil, nsync_malloc_ptr_ points to a malloc-like routine that allocated

   memory, used by mutex and condition variable code to allocate waiter

   structs.  This would allow nsync's mutexes to be used inside an

   implementation of malloc(), by providing another, simpler allocator here.

   The intent is that the implicit NULL value here can be overridden by a

   client declaration that uses an initializer.  */

void *(*nsync_malloc_ptr_) (size_t size);

/* Return a pointer to an unused waiter struct.

   Ensures that the enclosed timer is stopped and its channel drained. */

waiter *nsync_waiter_new_ (void) {

  nsync_dll_element_ *q;

  waiter *tw;

  waiter *w;

  if (HAVE_THREAD_LOCAL) {

    tw = waiter_for_thread;

  } else {

    tw = (waiter *) nsync_per_thread_waiter_ (&waiter_destroy);

  }

  w = tw;

  if (w == NULL || (w->flags & (WAITER_RESERVED|WAITER_IN_USE)) != WAITER_RESERVED) {

    w = NULL;

    nsync_spin_test_and_set_ (&free_waiters_mu, 1, 1, 0);

    q = nsync_dll_first_ (free_waiters);

    if (q != NULL) { /* If free list is non-empty, dequeue an item. */

      free_waiters = nsync_dll_remove_ (free_waiters, q);

      w = DLL_WAITER (q);

    }

    ATM_STORE_REL (&free_waiters_mu, 0); /* release store */

    if (w == NULL) { /* If free list was empty, allocate an item. */

      if (nsync_malloc_ptr_ != NULL) { /* Use client's malloc() */

        w = (waiter *) (*nsync_malloc_ptr_) (sizeof (*w));

      } else {  /* standard malloc () */

        w = (waiter *) malloc (sizeof (*w));

      }

      w->tag = WAITER_TAG;

      w->nw.tag = NSYNC_WAITER_TAG;

      nsync_mu_semaphore_init (&w->sem);

      w->nw.sem = &w->sem;

      nsync_dll_init_ (&w->nw.q, &w->nw);

      NSYNC_ATOMIC_UINT32_STORE_ (&w->nw.waiting, 0);

      w->nw.flags = NSYNC_WAITER_FLAG_MUCV;

      ATM_STORE (&w->remove_count, 0);

      nsync_dll_init_ (&w->same_condition, w);

      w->flags = 0;

    }

    if (tw == NULL) {

      w->flags |= WAITER_RESERVED;

      nsync_set_per_thread_waiter_ (w, &waiter_destroy);

      if (HAVE_THREAD_LOCAL) {

        waiter_for_thread = w;

      }

    }

  }

  w->flags |= WAITER_IN_USE;

  return (w);

}

/* Return an unused waiter struct *w to the free pool. */

void nsync_waiter_free_ (waiter *w) {

  ASSERT ((w->flags & WAITER_IN_USE) != 0);

  w->flags &= ~WAITER_IN_USE;

  if ((w->flags & WAITER_RESERVED) == 0) {

    nsync_spin_test_and_set_ (&free_waiters_mu, 1, 1, 0);

    free_waiters = nsync_dll_make_first_in_list_ (free_waiters, &w->nw.q);

    ATM_STORE_REL (&free_waiters_mu, 0); /* release store */

  }

}

/* ====================================================================================== */

/* writer_type points to a lock_type that describes how to manipulate a mu for a writer. */

static lock_type Xwriter_type = {

  MU_WZERO_TO_ACQUIRE,

  MU_WADD_TO_ACQUIRE,

  MU_WHELD_IF_NON_ZERO,

  MU_WSET_WHEN_WAITING,

  MU_WCLEAR_ON_ACQUIRE,

  MU_WCLEAR_ON_UNCONTENDED_RELEASE

};

lock_type *nsync_writer_type_ = &Xwriter_type;

/* reader_type points to a lock_type that describes how to manipulate a mu for a reader. */

static lock_type Xreader_type = {

  MU_RZERO_TO_ACQUIRE,

  MU_RADD_TO_ACQUIRE,

  MU_RHELD_IF_NON_ZERO,

  MU_RSET_WHEN_WAITING,

  MU_RCLEAR_ON_ACQUIRE,

  MU_RCLEAR_ON_UNCONTENDED_RELEASE

};

lock_type *nsync_reader_type_ = &Xreader_type;

NSYNC_CPP_END_