xtd::threading::thread Class Reference

Inheritance diagram for xtd::threading::thread:

Definition

Creates and controls a thread, sets its priority, and gets its status.

class core_export_ thread final : public xtd::object

Inheritance

xtd::object → xtd::threading::thread

Header

#include <xtd/threading/thread> 

Namespace

xtd::threading

Library

xtd.core

Examples

The following example demonstrates simple threading functionality.

#include <xtd/threading/thread>
#include <xtd/console>
#include <xtd/startup>
 
using namespace xtd;
using namespace xtd::threading;
 
// Simple threading scenario:  Start a static method running
// on a second thread.
class thread_example {
public:
  // The thread_proc method is called when the thread starts.
  // It loops ten times, writing to the console and yielding
  // the rest of its time slice each time, and then ends.
  static void thread_proc() {
    for (auto i = 0; i < 10; ++i) {
      console::write_line("thread_proc: {0}", i);
      // Yield the rest of the time slice.
      thread::sleep(0);
    }
  }
  
  static void main() {
    console::write_line("Main thread: Start a second thread.");
    // The constructor for the thread class requires a thread_start
    // delegate that represents the method to be executed on the
    // thread. xtd simplifies the creation of this delegate.
    auto t = thread {thread_proc};
    
    // Start thread_proc. Note that on a uniprocessor, the new
    // thread does not get any processor time until the main thread
    // is preempted or yields. Uncomment the thread::sleep that
    // follows t.start() to see the difference.
    t.start();
    //thread::sleep(0);
    
    for (auto i = 0; i < 4; ++i) {
      console::write_line("Main thread: Do some work.");
      thread::sleep(0);
    }
    
    console::write_line("Main thread: Call join(), to wait until thread_proc ends.");
    t.join();
    console::write_line("Main thread: thread_proc.join has returned.  Press Enter to end program.");
    console::read_line();
  }
};
 
startup_(thread_example::main);
 
// This code can produce the following output:
//
// Main thread: Start a second thread.
// Main thread: Do some work.
// Main thread: Do some work.
// thread_proc: 0
// Main thread: Do some work.
// thread_proc: 1
// Main thread: Do some work.
// thread_proc: 2
// Main thread: Call join(), to wait until thread_proc ends.
// thread_proc: 3
// thread_proc: 4
// thread_proc: 5
// thread_proc: 6
// thread_proc: 7
// thread_proc: 8
// thread_proc: 9
// Main thread: thread_proc.join has returned.  Press Enter to end program.

Remarks

When a process starts, the system automatically creates a single foreground thread to execute application code. Along with this main foreground thread, a process can create one or more threads to execute a portion of the program code associated with the process. These threads can execute either in the foreground or in the background. In addition, you can use the xtd::threading::thread_pool class to execute code on worker threads that are managed by the framework xrd.

Examples

environment_program_exit.cpp, event_wait_handle.cpp, exception_ptr.cpp, interlocked.cpp, interlocked_decrement.cpp, lock_guard.cpp, mixing_std_and_xtd_threads.cpp, monitor.cpp, network_stream.cpp, socket_tcp_ip_v4.cpp, socket_tcp_ip_v6.cpp, socket_udp_ip_v4.cpp, socket_udp_ip_v6.cpp, tcp_client_ip_v4.cpp, tcp_client_ip_v6.cpp, thread.cpp, timeout.cpp, udp_client_ip_v4.cpp, and udp_client_ip_v6.cpp.

Public Fields
static const intptr	invalid_handle
	Represents an invalid native operating system handle. This field is read-only.
static const intptr	invalid_thread_id
	Represents an invalid native operating system thread id. This field is read-only.

Cosntructors
	thread (const xtd::threading::parameterized_thread_start &start)
	Initializes a new instance of the xtd::threading::thread class, specifying a delegate that allows an object to be passed to the thread when the thread is started.
	thread (const xtd::threading::parameterized_thread_start &start, int32 max_stack_size)
	Initializes a new instance of the xtd::threading::thread class, specifying a delegate that allows an object to be passed to the thread when the thread is started and specifying the maximum stack size for the thread.
	thread (const xtd::threading::thread_start &start)
	Initializes a new instance of the xtd::threading::thread class.
	thread (const xtd::threading::thread_start &start, int32 max_stack_size)
	Initializes a new instance of the xtd::threading::thread class, specifying the maximum stack size for the thread.

Public Properties
intptr	handle () const noexcept
	Gets the native operating system handle.
bool	is_alive () const noexcept
	Gets a value indicating the execution status of the current thread.
bool	is_background () const noexcept
	Gets a value indicating whether or not a thread is a background thread.
thread &	is_background (bool value)
	Sets a value indicating whether or not a thread is a background thread.
bool	is_main_thread () const noexcept
	Gets a value indicating the current thread is the main thread.
bool	is_thread_pool_thread () const noexcept
	Gets a value indicating whether or not a thread belongs to the managed thread pool.
bool	joinable () const noexcept
	Gets a value indicating the current thread is joinable.
int32	managed_thread_id () const noexcept
	Gets a unique identifier for the current managed thread.
ustring	name () const noexcept
	Gets the name of the thread.
thread &	name (const ustring &value)
	Sets the name of the thread.
xtd::threading::thread_priority	priority () const noexcept
	Gets a value indicating the scheduling priority of a thread.
thread &	priority (xtd::threading::thread_priority value)
	Sets a value indicating the scheduling priority of a thread.
intptr	thread_id () const noexcept
	Gets the native operating system thread id.
xtd::threading::thread_state	thread_state () const noexcept
	Gets a value containing the states of the current thread.

Public Methods
void	abort ()
	Raises a xtd::threading::thread_aborted_exception in the thread on which it is invoked, to begin the process of terminating the thread. Calling this method usually terminates the thread.
void	detach ()
	Sets the thread background.
void	interrupt ()
	Interrupts a thread that is in the xtd::threading::thread_state::wait_sleep_join thread state.
void	join ()
	Blocks the calling thread until this thread object terminates, while continuing to perform standard COM and SendMessage pumping.
bool	join (int32 milliseconds_timeout)
	Blocks the calling thread until this thread object terminates or the specified time elapses, while continuing to perform standard COM and SendMessage pumping.
bool	join (const time_span &timeout)
	Blocks the calling thread until this thread object terminates or the specified time elapses, while continuing to perform standard COM and SendMessage pumping.
void	resume ()
	Resumes a thread that has been suspended (Should not be used).
void	start ()
	Causes the operating system to change the state of the current instance to xtd::threading::thread_state::running.
void	start (std::any obj)
	Causes the operating system to change the state of the current instance to xtd::threading::thread_state::running.
void	suspend ()
	Either suspends the thread, or if the thread is already suspended, has no effect (Should not be used).

Public Static Properties
static thread &	current_thread () noexcept
	Gets the currently running thread.
static thread &	main_thread ()
	Gets the main thread.

Public Static Methods
static thread	start_new (const xtd::threading::thread_start &start)
	Create and immedialtely start a xtd::threading::thread with specified method.
static thread	start_new (const xtd::threading::parameterized_thread_start &start, std::any obj)
	Create and immedialtely start a xtd::threading::thread with specified method.
static void	join_all ()
	Blocks the calling thread until all joinable threads terminate.
static bool	join_all (int32 milliseconds_timeout)
	Blocks the calling thread until all joinable threads terminate or the specified time elapses, while continuing.
static bool	join_all (const time_span &timeout)
	Blocks the calling thread until all joinable threads terminate or the specified time elapses, while continuing.
template<typename collection_t >
static void	join_all (const collection_t &threads)
	Blocks the calling thread until all specified joinable threads collection terminate.
template<typename collection_t >
static bool	join_all (const collection_t &threads, int32 milliseconds_timeout)
	Blocks the calling thread until all specified joinable threads collection terminate or the specified time elapses, while continuing.
template<typename collection_t >
static bool	join_all (const collection_t &threads, const time_span &timeout)
	Blocks the calling thread until all specified joinable threads collection terminate or the specified time elapses, while continuing.
static void	sleep (int32 milliseconds_timeout)
	Suspends the current thread for a specified time.
static void	sleep (const time_span &timeout)
	Suspends the current thread for a specified time.
static void	spin_wait (int32 iterations)
	Causes a thread to wait the number of times defined by the iterations parameter.
static bool	yield ()
	Causes the calling thread to yield execution to another thread that is ready to run on the current processor. The operating system selects the thread to yield to.

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
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 >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object.
virtual xtd::ustring	to_string () const noexcept
	Returns a sxd::ustring that represents the current object.
Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal.
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

thread() [1/4]

xtd::threading::thread::thread ( const xtd::threading::parameterized_thread_start &  start )

explicit

Initializes a new instance of the xtd::threading::thread class, specifying a delegate that allows an object to be passed to the thread when the thread is started.

Parameters

start

A delegate that represents the methods to be invoked when this thread begins executing.

Exceptions

xtd::argument_exception

The start parameter is empty.

Remarks

A thread does not begin executing when it is created. To schedule the thread for execution, call the xtd::threading::thread::start method. To pass a data object to the thread, use the xtd::threading::thread::start(std::any) method overload.

Examples

interlocked.cpp.

thread() [2/4]

xtd::threading::thread::thread	(	const xtd::threading::parameterized_thread_start &	start,
		int32	max_stack_size
	)

Initializes a new instance of the xtd::threading::thread class, specifying a delegate that allows an object to be passed to the thread when the thread is started and specifying the maximum stack size for the thread.

Parameters

start	A delegate that represents the methods to be invoked when this thread begins executing.
max_stack_size	The maximum stack size, in bytes, to be used by the thread, or 0 to use the default maximum stack size specified in the header for the executable. Important For partially trusted code, max_stack_size is ignored if it is greater than the default stack size. No exception is thrown.

Exceptions

xtd::argument_exception

The start parameter is empty.

Remarks

A thread does not begin executing when it is created. To schedule the thread for execution, call the xtd::threading::thread::start method. To pass a data object to the thread, use the xtd::threading::thread::start(std::any) method overload.

thread() [3/4]

xtd::threading::thread::thread ( const xtd::threading::thread_start &  start )

explicit

Initializes a new instance of the xtd::threading::thread class.

Parameters

start	A xtd::threading::thread_start delegate that represents the methods to be invoked when this thread begins executing.
max_stack_size	The maximum stack size, in bytes, to be used by the thread, or 0 to use the default maximum stack size specified in the header for the executable. Important For partially trusted code, max_stack_size is ignored if it is greater than the default stack size. No exception is thrown.

Exceptions

xtd::argument_exception

The start parameter is empty.

Remarks

A thread does not begin executing when it is created. To schedule the thread for execution, call the xtd::threading::thread::start method.

thread() [4/4]

xtd::threading::thread::thread	(	const xtd::threading::thread_start &	start,
		int32	max_stack_size
	)

Initializes a new instance of the xtd::threading::thread class, specifying the maximum stack size for the thread.

Parameters

start	A xtd::threading::thread_start delegate that represents the methods to be invoked when this thread begins executing.
max_stack_size	The maximum stack size, in bytes, to be used by the thread, or 0 to use the default maximum stack size specified in the header for the executable. Important For partially trusted code, max_stack_size is ignored if it is greater than the default stack size. No exception is thrown.

Exceptions

xtd::argument_exception

The start parameter is empty.

Remarks

A thread does not begin executing when it is created. To schedule the thread for execution, call the xtd::threading::thread::start method.

Member Function Documentation

abort()

void xtd::threading::thread::abort

(

)

Raises a xtd::threading::thread_aborted_exception in the thread on which it is invoked, to begin the process of terminating the thread. Calling this method usually terminates the thread.

Exceptions

xtd::threading::thread_aborted_exception

The thread that is being aborted is currently suspended.

current_thread()

static thread & xtd::threading::thread::current_thread ( )

staticnoexcept

Gets the currently running thread.

Returns

A xtd::threading::thread that is the representation of the currently running thread.

detach()

void xtd::threading::thread::detach

(

)

Sets the thread background.

Remarks

This method is identical to the call to xtd::threading::thread::is_background(true).

handle()

intptr xtd::threading::thread::handle ( ) const

noexcept

Gets the native operating system handle.

Returns

An intptr representing the native operating system handle.

interrupt()

void xtd::threading::thread::interrupt

(

)

Interrupts a thread that is in the xtd::threading::thread_state::wait_sleep_join thread state.

Remarks

If this thread is not currently blocked in a thread_state::wait, thread_state::sleep, or thread_state::join state, it will be interrupted when it next begins to block.

xtd::threading::thread_interrupted_exception is thrown in the interrupted thread, but not until the thread blocks. If the thread never blocks, the exception is never thrown, and thus the thread might complete without ever being interrupted.

is_alive()

bool xtd::threading::thread::is_alive ( ) const

noexcept

Gets a value indicating the execution status of the current thread.

Returns

true if this thread has been started and has not terminated normally or aborted; otherwise, false.

is_background() [1/2]

bool xtd::threading::thread::is_background ( ) const

noexcept

Gets a value indicating whether or not a thread is a background thread.

Returns

true if this thread is or is to become a background thread; otherwise, false.

Exceptions

xtd::threadng::thread_state_exception

The thread is dead.

Remarks

A thread is either a background thread or a foreground thread. Background threads are identical to foreground threads, except that background threads do not prevent a process from terminating. Once all foreground threads belonging to a process have terminated, the system ends the process. Any remaining background threads are stopped and do not complete.

By default, the following threads execute in the foreground (that is, their xtd::threading::thread::is_background property returns false):

• The primary thread (or main application thread).
• All threads created by calling a xtd::threading::thread class constructor.

By default, the following threads execute in the background (that is, their xtd::threading::thread::is_background property returns true):

• Thread pool threads, which are a pool of worker threads maintained by the runtime. You can configure the thread pool and schedule work on thread pool threads by using the xtd::threading::thread_pool class.
• All threads create without xtd::threading::thread class (std::thread or threads create by oparating system API).

is_background() [2/2]

thread & xtd::threading::thread::is_background

(

bool

value

)

Sets a value indicating whether or not a thread is a background thread.

Parameters

value

true if this thread is or is to become a background thread; otherwise, false.

Exceptions

xtd::threadng::thread_state_exception

The thread is dead.

Remarks

A thread is either a background thread or a foreground thread. Background threads are identical to foreground threads, except that background threads do not prevent a process from terminating. Once all foreground threads belonging to a process have terminated, the system ends the process. Any remaining background threads are stopped and do not complete.

By default, the following threads execute in the foreground (that is, their xtd::threading::thread::is_background property returns false):

• The primary thread (or main application thread).
• All threads created by calling a xtd::threading::thread class constructor.

By default, the following threads execute in the background (that is, their xtd::threading::thread::is_background property returns true):

• Thread pool threads, which are a pool of worker threads maintained by the runtime. You can configure the thread pool and schedule work on thread pool threads by using the xtd::threading::thread_pool class.
• All threads create without xtd::threading::thread class (std::thread or threads create by oparating system API).

is_main_thread()

bool xtd::threading::thread::is_main_thread ( ) const

noexcept

Gets a value indicating the current thread is the main thread.

Returns

true if this thread is the main thread; otherwise, false.

is_thread_pool_thread()

bool xtd::threading::thread::is_thread_pool_thread ( ) const

noexcept

Gets a value indicating whether or not a thread belongs to the managed thread pool.

Returns

true if this thread belongs to the managed thread pool; otherwise, false.

Remarks

For more information see xtd::threading::thread_pool.

join() [1/3]

void xtd::threading::thread::join

(

)

Blocks the calling thread until this thread object terminates, while continuing to perform standard COM and SendMessage pumping.

Exceptions

xtd::threading::thread_state_exception

The caller attempted to join a thread that is in the xtd::threading::thread_state::unstarted state.

Examples

interlocked.cpp, lock_guard.cpp, and monitor.cpp.

join() [2/3]

bool xtd::threading::thread::join

(

const time_span &

timeout

)

Blocks the calling thread until this thread object terminates or the specified time elapses, while continuing to perform standard COM and SendMessage pumping.

Parameters

timeout

A xtd::time_span set to the amount of time to wait for the thread to terminate.

Returns

true if the thread has terminated; false if the thread has not terminated after the amount of time specified by the xtd::milliseconds_timeout parameter has elapsed.

Exceptions

xtd::threading::thread_state_exception	The caller attempted to join a thread that is in the xtd::threading::thread_state::unstarted state.
xtd::argument_exception	timeout is a negative number other than -1 milliseconds, which represents -or- timeout is greater than xtd::int32_object::max_value.

join() [3/3]

bool xtd::threading::thread::join

(

int32

milliseconds_timeout

)

Blocks the calling thread until this thread object terminates or the specified time elapses, while continuing to perform standard COM and SendMessage pumping.

Parameters

milliseconds_timeout

The number of milliseconds to wait for the thread to terminate.

Returns

true if the thread has terminated; false if the thread has not terminated after the amount of time specified by the xtd::milliseconds_timeout parameter has elapsed.

Exceptions

xtd::threading::thread_state_exception	The caller attempted to join a thread that is in the xtd::threading::thread_state::unstarted state.
xtd::argument_out_of_range_rxception	milliseconds_timeout is a negative number other than -1, which represents an infinite time-out.

join_all() [1/6]

static void xtd::threading::thread::join_all ( )

static

Blocks the calling thread until all joinable threads terminate.

Exceptions

xtd::threading::thread_state_exception

The caller attempted to join a thread that is in the xtd::threading::thread_state::unstarted state.

Remarks

If one or more threads are not joinable, they will be skipped.

The xtd::startup::run method and startup_ keyword call the xtd::threading::thread::join_all method.

Call xtd::threading::thread_pool::close method to join the end of running worker threads too.

join_all() [2/6]

template<typename collection_t >

static void xtd::threading::thread::join_all ( const collection_t &  threads )

inlinestatic

Blocks the calling thread until all specified joinable threads collection terminate.

Exceptions

xtd::threading::thread_state_exception

The caller attempted to join a thread that is in the xtd::threading::thread_state::unstarted state.

Remarks

If one or more threads are not joinable, they will be skipped.

join_all() [3/6]

template<typename collection_t >

static bool xtd::threading::thread::join_all ( const collection_t &  threads, const time_span &  timeout  )

inlinestatic

Blocks the calling thread until all specified joinable threads collection terminate or the specified time elapses, while continuing.

Parameters

timeout

A xtd::time_span set to the amount of time to wait for all threads to terminate.

Returns

true if all threads have terminated; false if all threads have not terminated after the amount of time specified by the timeout parameter has elapsed.

Exceptions

xtd::threading::thread_state_exception

The caller attempted to join a thread that is in the xtd::threading::thread_state::unstarted state.

Remarks

If one or more threads are not joinable, they will be skipped.

join_all() [4/6]

template<typename collection_t >

static bool xtd::threading::thread::join_all ( const collection_t &  threads, int32  milliseconds_timeout  )

inlinestatic

Blocks the calling thread until all specified joinable threads collection terminate or the specified time elapses, while continuing.

Parameters

milliseconds_timeout

The number of milliseconds to wait for all threads to terminate.

Returns

true if all threads have terminated; false if all threads have not terminated after the amount of time specified by the timeout parameter has elapsed.

Exceptions

xtd::threading::thread_state_exception

The caller attempted to join a thread that is in the xtd::threading::thread_state::unstarted state.

Remarks

If one or more threads are not joinable, they will be skipped.

join_all() [5/6]

static bool xtd::threading::thread::join_all ( const time_span &  timeout )

static

Blocks the calling thread until all joinable threads terminate or the specified time elapses, while continuing.

Parameters

timeout

A xtd::time_span set to the amount of time to wait for all threads to terminate.

Returns

true if all threads have terminated; false if all threads have not terminated after the amount of time specified by the timeout parameter has elapsed.

Exceptions

xtd::threading::thread_state_exception

The caller attempted to join a thread that is in the xtd::threading::thread_state::unstarted state.

Remarks

If one or more threads are not joinable, they will be skipped.

Call xtd::threading::thread_pool::close method to join the end of running worker threads too.

join_all() [6/6]

static bool xtd::threading::thread::join_all ( int32  milliseconds_timeout )

static

Blocks the calling thread until all joinable threads terminate or the specified time elapses, while continuing.

Parameters

milliseconds_timeout

The number of milliseconds to wait for all threads to terminate.

Returns

true if all threads have terminated; false if all threads have not terminated after the amount of time specified by the timeout parameter has elapsed.

Exceptions

xtd::threading::thread_state_exception

The caller attempted to join a thread that is in the xtd::threading::thread_state::unstarted state.

Remarks

If one or more threads are not joinable, they will be skipped.

Call xtd::threading::thread_pool::close method to join the end of running worker threads too.

joinable()

bool xtd::threading::thread::joinable ( ) const

noexcept

Gets a value indicating the current thread is joinable.

Returns

true if this thread is joinable; otherwise, false.

Remarks

A thread is joinable if it started, not stopped and if is not a background thread.

if the thread is joinable you can call the xtd::threading::thread::join method.

main_thread()

static thread & xtd::threading::thread::main_thread ( )

static

Gets the main thread.

Returns

A xtd::threading::thread that is the representation of the main thread.

Remarks

if the thread is not started this method return xtd::threading::thread::invalid_handle.

managed_thread_id()

int32 xtd::threading::thread::managed_thread_id ( ) const

noexcept

Gets a unique identifier for the current managed thread.

Returns

An integer that represents a unique identifier for this managed thread.

Remarks

A thread's xtd::threading::thread::managed_thread_id property value serves to uniquely identify that thread within its process.

The value of the xtd::threading::thread::managed_thread_id property does not vary over time

Examples

mixing_std_and_xtd_threads.cpp.

name() [1/2]

ustring xtd::threading::thread::name ( ) const

noexcept

Gets the name of the thread.

Returns

A string containing the name of the thread, or empty ("") if no name was set.

Examples

mixing_std_and_xtd_threads.cpp.

name() [2/2]

thread & xtd::threading::thread::name

(

const ustring &

value

)

Sets the name of the thread.

Parameters

value

A string containing the name of the thread, or empty ("") if no name was set.

priority() [1/2]

xtd::threading::thread_priority xtd::threading::thread::priority ( ) const

noexcept

Gets a value indicating the scheduling priority of a thread.

Returns

One of the xtd::threading::thread_priority values. The default value is xtd::threading::thread_priority::normal.

Exceptions

xtd::threading::thread_state_exception	The thread has reached a final state, such as Aborted.
xtd::argument_exception	The value specified for a set operation is not a valid xtd::threading::thread_priority value.

Remarks

A thread can be assigned any one of the following priority xtd::threading::thread_priority values:

• highest
• above_normal
• normal
• below_normal
• lowest

Examples

mixing_std_and_xtd_threads.cpp.

priority() [2/2]

thread & xtd::threading::thread::priority

(

xtd::threading::thread_priority

value

)

Sets a value indicating the scheduling priority of a thread.

Parameters

value

One of the xtd::threading::thread_priority values. The default value is xtd::threading::thread_priority::normal.

Exceptions

xtd::threading::thread_state_exception	The thread has reached a final state, such as Aborted.
xtd::argument_exception	The value specified for a set operation is not a valid xtd::threading::thread_priority value.

Remarks

A thread can be assigned any one of the following priority xtd::threading::thread_priority values:

• highest
• above_normal
• normal
• below_normal
• lowest

resume()

void xtd::threading::thread::resume

(

)

Resumes a thread that has been suspended (Should not be used).

Exceptions

xtd::threading::thread_state_exception

The thread has not been started, is dead, or is not in the suspended state.

Remarks

Works only on Windows operating syetm.

Warning

Do not use the xtd::threading::thread::suspend and xtd::threading::thread::resume methods to synchronize the activities of threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while it holds locks during a security permission evaluation, other threads in the application might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the application that attempt to use that class are blocked. Deadlocks can occur very easily.

sleep() [1/2]

static void xtd::threading::thread::sleep ( const time_span &  timeout )

static

Suspends the current thread for a specified time.

Parameters

timeout

A std::chrono::duration set to the amount of time for which the thread is blocked. Specify zero to indicate that this thread should be suspended to allow other waiting threads to execute. Specify xtd::threading::Timeout.Infinite to block the thread indefinitely.

Exceptions

xtd::argument_exception

The value of timeout is negative and is not equal to xtd::threading::timeout::infinite in milliseconds, or is greater than xtd::Int32.MaxValue milliseconds.

sleep() [2/2]

static void xtd::threading::thread::sleep ( int32  milliseconds_timeout )

static

Suspends the current thread for a specified time.

Parameters

milliseconds_timeout

The number of milliseconds for which the thread is blocked. Specify zero (0) to indicate that this thread should be suspended to allow other waiting threads to execute. Specify xtd::threading::Timeout.Infinite to block the thread indefinitely.

Exceptions

xtd::argument_exception

milliseconds_timeout is a negative number other than -1, which represents an infinite time-out.

spin_wait()

static void xtd::threading::thread::spin_wait ( int32  iterations )

static

Causes a thread to wait the number of times defined by the iterations parameter.

Parameters

iterations

A 32-bit signed integer that defines how long a thread is to wait.

Remarks

The xtd::threading::thread::spin_wait method is useful for implementing locks. Classes in the xtd, such as xtd::threading::monitor and xtd::threading::reader_writer_lock, use this method internally. xtd::threading::thread::spin_wait essentially puts the processor into a very tight loop, with the loop count specified by the iterations parameter. The duration of the wait therefore depends on the speed of the processor.

Contrast this with the xtd::threading::thread::sleep method. A thread that calls xtd::threading::thread::sleep yields the rest of its current slice of processor time, even if the specified interval is zero. Specifying a non-zero interval for xtd::threading::thread::sleep removes the thread from consideration by the thread scheduler until the time interval has elapsed.

xtd::threading::thread::spin_wait is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by the xtd Framework; for example, call xtd::threading::monitor::enter or a statement that wraps xtd::threading::thread::monitor::enter

start() [1/2]

void xtd::threading::thread::start

(

)

Causes the operating system to change the state of the current instance to xtd::threading::thread_state::running.

Exceptions

xtd::threading::thread_state_exception

The thread has already been started.

Examples

event_wait_handle.cpp, interlocked_decrement.cpp, and timeout.cpp.

start() [2/2]

void xtd::threading::thread::start

(

std::any

obj

)

Causes the operating system to change the state of the current instance to xtd::threading::thread_state::running.

Parameters

obj	An object that contains data to be used by the method the thread executes.

Exceptions

xtd::threading::thread_state_exception

The thread has already been started.

start_new() [1/2]

static thread xtd::threading::thread::start_new ( const xtd::threading::parameterized_thread_start &  start, std::any  obj  )

static

Create and immedialtely start a xtd::threading::thread with specified method.

Parameters

start	A delegate that represents the methods to be invoked when this thread begins executing.
obj	An object that contains data to be used by the method the thread executes.

Exceptions

xtd::argument_exception

The start parameter is empty.

start_new() [2/2]

static thread xtd::threading::thread::start_new ( const xtd::threading::thread_start &  start )

static

Create and immedialtely start a xtd::threading::thread with specified method.

Parameters

start

A delegate that represents the methods to be invoked when this thread begins executing.

Exceptions

xtd::argument_exception

The start parameter is empty.

suspend()

void xtd::threading::thread::suspend

(

)

Either suspends the thread, or if the thread is already suspended, has no effect (Should not be used).

Exceptions

xtd::threading::thread_state_exception

The thread has not been started or is dead.

Remarks

Works only on Windows operating syetm.

Warning

Do not use the xtd::threading::thread::suspend and xtd::threading::thread::resume methods to synchronize the activities of threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while it holds locks during a security permission evaluation, other threads in the application might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the application that attempt to use that class are blocked. Deadlocks can occur very easily.

thread_id()

intptr xtd::threading::thread::thread_id ( ) const

noexcept

Gets the native operating system thread id.

Returns

An intptr representing the native operating thread id.

Remarks

if the thread is not started this method return xtd::threading::thread::invalid_thread_id.

Examples

mixing_std_and_xtd_threads.cpp.

thread_state()

xtd::threading::thread_state xtd::threading::thread::thread_state ( ) const

noexcept

Gets a value containing the states of the current thread.

Returns

One of the xtd::threading::thread_state values indicating the state of the current thread. The initial value is xtd::threading::thread_state::unstarted.

Remarks

The xtd::threading::thread::thread_state property provides more specific information than the xtd::threading::thread::is_alive property.

Warning

Thread state is only of interest in debugging scenarios. Your code should never use thread state to synchronize the activities of threads.

Examples

mixing_std_and_xtd_threads.cpp.

yield()

static bool xtd::threading::thread::yield ( )

static

Causes the calling thread to yield execution to another thread that is ready to run on the current processor. The operating system selects the thread to yield to.

Returns

true if the operating system switched execution to another thread; otherwise, false.

Remarks

If this method succeeds, the rest of the thread's current time slice is yielded. The operating system schedules the calling thread for another time slice, according to its priority and the status of other threads that are available to run.

yielding is limited to the processor that is executing the calling thread. The operating system will not switch execution to another processor, even if that processor is idle or is running a thread of lower priority. If there are no other threads that are ready to execute on the current processor, the operating system does not yield execution, and this method returns false.

This method is equivalent to using platform invoke to call the native Win32 switch_to_thread function. You should call the xtd::threading::thread::yield method instead of using platform invoke, because platform invoke bypasses any custom threading behavior the host has requested.

Member Data Documentation

invalid_handle

const intptr xtd::threading::thread::invalid_handle

static

Represents an invalid native operating system handle. This field is read-only.

Remarks

Used internally to initialize the xtd::thread::wait_handle::handle property.

invalid_thread_id

const intptr xtd::threading::thread::invalid_thread_id

static

Represents an invalid native operating system thread id. This field is read-only.

Remarks

Used internally to initialize the xtd::threading::thread::thread_id property.

---

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

• xtd.core/include/xtd/threading/thread.h