xtd 0.2.0
Loading...
Searching...
No Matches
xtd::threading::spin_lock Class Reference
Inheritance diagram for xtd::threading::spin_lock:
xtd::object

Definition

Provides a mutual exclusion lock primitive where a thread trying to acquire the lock waits in a loop repeatedly checking until the lock becomes available.

class spin_lock : public xtd::object
Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.h:42
Provides a mutual exclusion lock primitive where a thread trying to acquire the lock waits in a loop ...
Definition spin_lock.h:36
Header
#include <xtd/threading/spin_lock>
Namespace
xtd::threading
Library
xtd.core
Examples
The following example shows how to use a xtd::threading::spin_lock:
Remarks
Spin locks can be used for leaf-level locks where the object allocation implied by using a xtd::threading::monitor, in size, is overly expensive. A spin lock can be useful to avoid blocking; however, if you expect a significant amount of blocking, you should probably not use spin locks due to excessive spinning. Spinning can be beneficial when locks are fine-grained and large in number (for example, a lock per node in a linked list) and also when lock hold-times are always extremely short. In general, while holding a spin lock, one should avoid any of these actions:
  • blocking,
  • calling anything that itself may block,
  • holding more than one spin lock at once,
  • making dynamically dispatched calls (interface and virtuals),
  • making statically dispatched calls into any code one doesn't own, or
  • allocating memory.
xtd::threading::spin_lock should only be used after you have been determined that doing so will improve an application's performance. It is also important to note that xtd::threading::spin_lock is a value type, for performance reasons. For this reason, you must be very careful not to accidentally copy a xtd::threading::spin_lock instance, as the two instances (the original and the copy) would then be completely independent of one another, which would likely lead to erroneous behavior of the application. If a xtd::threading::spin_lock instance must be passed around, it should be passed by reference rather than by value.

Public Constructors

 spin_lock ()
 Initializes a new instance of the xtd::threading::spin_lock structure.
 
 spin_lock (bool enable_thread_owner_tracking)
 Initializes a new instance of the xtd::threading::spin_lock structure with the option to track thread IDs to improve debugging.
 

Public Properties

bool is_held () const noexcept
 Gets whether the lock is currently held by any thread.
 
bool is_held_by_current_thread () const noexcept
 Gets whether the lock is held by the current thread.
 
bool is_thread_owner_tracking_enabled () const noexcept
 Gets whether thread ownership tracking is enabled for this instance.
 

Public Methods

void enter (bool &lock_taken)
 Acquires the lock in a reliable manner, such that even if an exception occurs within the method call, lock_taken can be examined reliably to determine whether the lock was acquired.
 
void exit ()
 Releases the lock.
 
void exit (bool use_memory_barrier)
 Releases the lock.
 
void try_enter (bool &lock_taken)
 Attempts to acquire the lock in a reliable manner, such that even if an exception occurs within the method call, lock_taken can be examined reliably to determine whether the lock was acquired.
 
void try_enter (int32 milliseconds_timeout, bool &lock_taken)
 Attempts to acquire the lock in a reliable manner, such that even if an exception occurs within the method call, lock_taken can be examined reliably to determine whether the lock was acquired.
 
void try_enter (const time_span &timeout, bool &lock_taken)
 Attempts to acquire the lock in a reliable manner, such that even if an exception occurs within the method call, lock_taken can be examined reliably to determine whether the lock was acquired.
 

Additional Inherited Members

- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object.
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object.
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type.
 
virtual type_object get_type () const noexcept
 Gets the type of the current instance.
 
template<typename object_t >
xtd::uptr< object_t > memberwise_clone () const
 Creates a shallow copy of the current object.
 
virtual xtd::string to_string () const noexcept
 Returns a xtd::string that represents the current object.
 
- Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename object_b_t >
static bool equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are considered equal.
 
template<typename object_a_t , typename object_b_t >
static bool reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are the same instance.
 

Constructor & Destructor Documentation

◆ spin_lock() [1/2]

xtd::threading::spin_lock::spin_lock ( )

Initializes a new instance of the xtd::threading::spin_lock structure.

◆ spin_lock() [2/2]

xtd::threading::spin_lock::spin_lock ( bool  enable_thread_owner_tracking)

Initializes a new instance of the xtd::threading::spin_lock structure with the option to track thread IDs to improve debugging.

Parameters
enable_thread_owner_trackingWhether to capture and use thread IDs for debugging purposes.
Remarks
The parameterless constructor for xtd::threading::spin_lock tracks thread ownership.

Member Function Documentation

◆ is_held()

bool xtd::threading::spin_lock::is_held ( ) const
noexcept

Gets whether the lock is currently held by any thread.

Returns
true if the lock is currently held by any thread; otherwise false.

◆ is_held_by_current_thread()

bool xtd::threading::spin_lock::is_held_by_current_thread ( ) const
noexcept

Gets whether the lock is held by the current thread.

Returns
true if the lock is held by the current thread; otherwise false.
Remarks
If the lock was initialized to track owner threads, this will return whether the lock is acquired by the current thread. It is invalid to use this property when the lock was initialized to not track thread ownership.

◆ is_thread_owner_tracking_enabled()

bool xtd::threading::spin_lock::is_thread_owner_tracking_enabled ( ) const
noexcept

Gets whether thread ownership tracking is enabled for this instance.

Returns
true if thread ownership tracking is enabled for this instance; otherwise false.

◆ enter()

void xtd::threading::spin_lock::enter ( bool &  lock_taken)

Acquires the lock in a reliable manner, such that even if an exception occurs within the method call, lock_taken can be examined reliably to determine whether the lock was acquired.

Parameters
lock_takenTrue if the lock is acquired; otherwise, false.
Exceptions
xtd::threading::lock_recursion_exceptionThread ownership tracking is enabled, and the current thread has already acquired this lock.
Remarks
xtd::threading::spin_lock is a non-reentrant lock, meaning that if a thread holds the lock, it is not allowed to enter the lock again. If thread ownership tracking is enabled (whether it's enabled is available through xtd::threading::spin_lock::is_thread_owner_tracking_enabled), an exception will be thrown when a thread tries to re-enter a lock it already holds. However, if thread ownership tracking is disabled, attempting to enter a lock already held will result in deadlock.

◆ exit() [1/2]

void xtd::threading::spin_lock::exit ( )

Releases the lock.

Exceptions
xtd::threading::synchronization_lock_exceptionThread ownership tracking is enabled, and the current thread is not the owner of this lock.
Remarks
The default overload of Exit provides the same behavior as if calling Exit using true as the argument.
If you call xtd::threading::spin_lock::exit without having first called xtd::threading::spin_lock::enter the internal state of the xtd::threading::spin_lock can become corrupted.

◆ exit() [2/2]

void xtd::threading::spin_lock::exit ( bool  use_memory_barrier)

Releases the lock.

Parameters
use_memory_barrierA bool value that indicates whether a memory fence should be issued in order to immediately publish the exit operation to other threads.
Exceptions
xtd::threading::synchronization_lock_exceptionThread ownership tracking is enabled, and the current thread is not the owner of this lock.
Remarks
Calling Exit with the use_memory_barrier argument set to true will improve the fairness of the lock at the expense of some performance. The default xtd::threading::spin_lock::exit overload behaves as if specifying true for use_memory_barrier.
If you call xtd::threading::spin_lock::exit without having first called xtd::threading::spin_lock::enter the internal state of the xtd::threading::spin_lock can become corrupted.

◆ try_enter() [1/3]

void xtd::threading::spin_lock::try_enter ( bool &  lock_taken)

Attempts to acquire the lock in a reliable manner, such that even if an exception occurs within the method call, lock_taken can be examined reliably to determine whether the lock was acquired.

Parameters
lock_takenTrue if the lock is acquired; otherwise, false.
Exceptions
xtd::threading::lock_recursion_exceptionThread ownership tracking is enabled, and the current thread has already acquired this lock.
Remarks
Unlike xtd::threading::spin_lock::enter, xtd::threading::spin_lock::try_enter will not block waiting for the lock to be available. If the lock is not available when xtd::threading::spin_lock::try_enter is called, it will return immediately without any further spinning.

◆ try_enter() [2/3]

void xtd::threading::spin_lock::try_enter ( int32  milliseconds_timeout,
bool &  lock_taken 
)

Attempts to acquire the lock in a reliable manner, such that even if an exception occurs within the method call, lock_taken can be examined reliably to determine whether the lock was acquired.

Parameters
milliseconds_timeoutThe number of milliseconds to wait, or xtd::threading::timeout::infinite (-1) to wait indefinitely.
lock_takenTrue if the lock is acquired; otherwise, false.
Exceptions
xtd::threading::lock_recursion_exceptionThread ownership tracking is enabled, and the current thread has already acquired this lock.
Remarks
Unlike xtd::threading::spin_lock::enter, xtd::threading::spin_lock::try_enter will not block indefinitely waiting for the lock to be available. It will block until either the lock is available or until the milliseconds_timeout has expired.

◆ try_enter() [3/3]

void xtd::threading::spin_lock::try_enter ( const time_span timeout,
bool &  lock_taken 
)

Attempts to acquire the lock in a reliable manner, such that even if an exception occurs within the method call, lock_taken can be examined reliably to determine whether the lock was acquired.

Parameters
timeoutA xtd::time_span that represents the number of milliseconds to wait, or a xtd::time_span that represents -1 milliseconds to wait indefinitely.
lock_takenTrue if the lock is acquired; otherwise, false.
Exceptions
xtd::threading::lock_recursion_exceptionThread ownership tracking is enabled, and the current thread has already acquired this lock.
Remarks
Unlike xtd::threading::spin_lock::enter, xtd::threading::spin_lock::try_enter will not block indefinitely waiting for the lock to be available. It will block until either the lock is available or until the timeout has expired.

The documentation for this class was generated from the following file: