<commit_before>// bsls_spinlock.h                                                    -*-C++-*-
#ifndef INCLUDED_BSLS_SPINLOCK
#define INCLUDED_BSLS_SPINLOCK

#ifndef INCLUDED_BSLS_IDENT
#include <bsls_ident.h>
#endif
BSLS_IDENT("$: $")

//@PURPOSE: Provide a spin lock.
//
//@CLASSES:
//       SpinLock: A mutex using "busy waiting" atomic operations.
//  SpinLockGuard: Automatic locking-unlocking of SpinLock
//
//@DESCRIPTION: This component provides a "busy wait" mutual exclusion lock
// primitive ("mutex"). A 'SpinLock' is small and statically-initializable, but
// because it "spins" in a tight loop rather than using system operations to
// block the thread of execution, it is unsuited for use cases involving high
// contention or long critical regions.  Additionally, this component does not
// provide any guarantee of fairness when multiple threads are contending for
// the same lock.  Use 'SpinLockGuard' for automatic locking-unlocking in a
// scope.
//
///Usage
///-----
// In this section we show intended use of this component.
//
///Example 1: Maintaining Static Count/Max Values
/// - - - - - - - - - - - - - - - - - - - - - - -
// Suppose that we want to determine the maximum number of threads executing a
// block of code concurrently.  Note that such a use case naturally calls for
// a statically initialized lock and the critical region involves a few integer
// operations; SpinLock may be suitable.
//
// First, we define a type to manage the count within a scope:
//..
// class MaxConcurrencyCounter {
//     // This type manages a count and high-water-mark within a scope.
//     // It decrements the count in its destructor upon leaving the scope.
//
//     // DATA
//     int            *d_count_p;
//     bsls::SpinLock *d_lock_p;
//
//   public:
//     // CREATORS
//     MaxConcurrencyCounter(int *count, int *max, bsls::SpinLock *lock);
//         // Acquire the specified 'lock' and increment the specified 'count'.<commit_msg>Adopt commit e7f7860 from master: Merge pull request #712 from bde/hvershce-spinlock-doc<commit_after>// bsls_spinlock.h                                                    -*-C++-*-
#ifndef INCLUDED_BSLS_SPINLOCK
#define INCLUDED_BSLS_SPINLOCK

#ifndef INCLUDED_BSLS_IDENT
#include <bsls_ident.h>
#endif
BSLS_IDENT("$: $")

//@PURPOSE: Provide a spin lock.
//
//@CLASSES:
//       SpinLock: A mutex using "busy waiting" atomic operations.
//  SpinLockGuard: Automatic locking-unlocking of SpinLock
//
//@DESCRIPTION: This component provides a "busy wait" mutual exclusion lock
// primitive ("mutex"). A 'SpinLock' is small and statically-initializable, but
// because it "spins" in a tight loop rather than using system operations to
// block the thread of execution, it is unsuited for use cases involving high
// contention or long critical regions.  Additionally, this component does not
// provide any guarantee of fairness when multiple threads are contending for
// the same lock.  Use 'SpinLockGuard' for automatic locking-unlocking in a
// scope.
//
// *WARNING*: A 'bsls::SpinLock' *must* be aggregate initialized to 
// 'BSLS_SPINLOCK_UNLOCKED'.  For example:
//..
//  bsls::SpinLock lock = BSLS_SPINLOCK_UNLOCKED;
//.. 
// Note that 'SpinLock' is a struct requiring aggregate initialization
// to allow lock variables to be staticially initalized when using a C++03 
// compiler (i.e., without using 'constexpr').
//
///Usage
///-----
// In this section we show intended use of this component.
//
///Example 1: Maintaining Static Count/Max Values
/// - - - - - - - - - - - - - - - - - - - - - - -
// Suppose that we want to determine the maximum number of threads executing a
// block of code concurrently.  Note that such a use case naturally calls for
// a statically initialized lock and the critical region involves a few integer
// operations; SpinLock may be suitable.
//
// First, we define a type to manage the count within a scope:
//..
// class MaxConcurrencyCounter {
//     // This type manages a count and high-water-mark within a scope.
//     // It decrements the count in its destructor upon leaving the scope.
//
//     // DATA
//     int            *d_count_p;
//     bsls::SpinLock *d_lock_p;
//
//   public:
//     // CREATORS
//     MaxConcurrencyCounter(int *count, int *max, bsls::SpinLock *lock);
//         // Acquire the specified 'lock' and increment the specified 'count'.
{'fraction_non_alphanumeric': 0.1142334932602239, 'fraction_numerical': 0.0027416038382453737, 'mean_word_length': 2.6513761467889907, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 10, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2466774', 'n_tokens_mistral': 1304, 'n_tokens_neox': 1235, 'n_words': 501}