xtd::threading::spin_lock Class Reference

Inheritance diagram for xtd::threading::spin_lock:

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

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
auto	is_held () const noexcept -> bool
	Gets whether the lock is currently held by any thread.
auto	is_held_by_current_thread () const noexcept -> bool
	Gets whether the lock is held by the current thread.
auto	is_thread_owner_tracking_enabled () const noexcept -> bool
	Gets whether thread ownership tracking is enabled for this instance.

Public Methods
auto	enter (bool &lock_taken) -> void
	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.
auto	exit () -> void
	Releases the lock.
auto	exit (bool use_memory_barrier) -> void
	Releases the lock.
auto	try_enter (bool &lock_taken) -> void
	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.
auto	try_enter (int32 milliseconds_timeout, bool &lock_taken) -> void
	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.
auto	try_enter (const time_span &timeout, bool &lock_taken) -> void
	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
	object ()=default
	Create a new instance of the ultimate base class object.
virtual auto	equals (const object &obj) const noexcept -> bool
	Determines whether the specified object is equal to the current object.
virtual auto	get_hash_code () const noexcept -> xtd::usize
	Serves as a hash function for a particular type.
virtual auto	get_type () const noexcept -> type_object
	Gets the type of the current instance.
template<typename object_t>
auto	memberwise_clone () const -> xtd::unique_ptr_object< object_t >
	Creates a shallow copy of the current object.
virtual auto	to_string () const -> xtd::string
	Returns a xtd::string that represents the current object.
template<typename object_a_t, typename object_b_t>
static auto	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are considered equal.
template<typename object_a_t, typename object_b_t>
static auto	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	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_tracking

Whether 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()

auto xtd::threading::spin_lock::is_held ( ) const -> bool

nodiscardnoexcept

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()

auto xtd::threading::spin_lock::is_held_by_current_thread ( ) const -> bool

nodiscardnoexcept

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()

auto xtd::threading::spin_lock::is_thread_owner_tracking_enabled ( ) const -> bool

nodiscardnoexcept

Gets whether thread ownership tracking is enabled for this instance.

Returns

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

enter()

auto xtd::threading::spin_lock::enter

(

bool &

lock_taken

)

-> void

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_taken

True if the lock is acquired; otherwise, false.

Exceptions

xtd::threading::lock_recursion_exception

Thread 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]

auto xtd::threading::spin_lock::exit

(

)

-> void

Releases the lock.

Exceptions

xtd::threading::synchronization_lock_exception

Thread 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]

auto xtd::threading::spin_lock::exit

(

bool

use_memory_barrier

)

-> void

Releases the lock.

Parameters

use_memory_barrier

A 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_exception

Thread 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]

auto xtd::threading::spin_lock::try_enter

(

bool &

lock_taken

)

-> void

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_taken

True if the lock is acquired; otherwise, false.

Exceptions

xtd::threading::lock_recursion_exception

Thread 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]

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

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_timeout	The number of milliseconds to wait, or xtd::threading::timeout::infinite (-1) to wait indefinitely.
lock_taken	True if the lock is acquired; otherwise, false.

Exceptions

xtd::threading::lock_recursion_exception

Thread 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]

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

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

timeout	A xtd::time_span that represents the number of milliseconds to wait, or a xtd::time_span that represents -1 milliseconds to wait indefinitely.
lock_taken	True if the lock is acquired; otherwise, false.

Exceptions

xtd::threading::lock_recursion_exception

Thread 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:

• xtd.core/include/xtd/threading/spin_lock.hpp