xtd::threading::jthread Class Reference

Inheritance diagram for xtd::threading::jthread:

Definition

Creates and controls an automatically rejoins on destruction thread, sets its priority, and gets its status.

class core_export_ jthread final : public xtd::threading::thread

Inheritance

xtd::object → xtd::threading::jthread

Header

#include <xtd/threading/jthread>

Namespace

xtd::threading

Library

xtd.core

Examples

The following example shows how to use xtd::threading::jthread.

#include <xtd/threading/jthread>
#include <xtd/block_scope>
#include <xtd/console>
 
using namespace xtd;
using namespace xtd::threading;
 
auto main() -> int {
  auto thread_proc = [] {
    thread::current_thread().name("thread_proc");
    for (auto index = 0; index < 10; ++index, thread::sleep(100_ms))
      console::write_line("  ({}) index = {}", thread::current_thread().name(), index);
  };
  
  thread::current_thread().name("main");
  console::write_line("({}) begin", thread::current_thread().name());
  block_scope_(auto thread1 = jthread::start_new(thread_proc)) {
    // Remarks :
    // * The `thread1` will be joined when the scope of the current block is closed.
    // * If you create `thread1` with xtd::threading::thread, `thread1` will be joined when the end of main.
    // * If you create `thread1` with std::jthread, `thread1` will be joined when the scope of the current block is closed too.
    // * If you create `thread1` with std::thread, there will be a runtime error.
    // You can try it yourself to see the different scenarios.
  }
  console::write_line("({}) end", thread::current_thread().name());
}
 
// This code can produce the following output if `thread1` is created with xtd::threading::jthread :
//
// (main) begin
//   (thread_proc) index = 0
//   (thread_proc) index = 1
//   (thread_proc) index = 2
//   (thread_proc) index = 3
//   (thread_proc) index = 4
//   (thread_proc) index = 5
//   (thread_proc) index = 6
//   (thread_proc) index = 7
//   (thread_proc) index = 8
//   (thread_proc) index = 9
// (main) end
 
// This code can produce the following output if `thread1` is created with xtd::threading::thread :
//
// (main) begin
// (main) end
//   (thread_proc) index = 0
//   (thread_proc) index = 1
//   (thread_proc) index = 2
//   (thread_proc) index = 3
//   (thread_proc) index = 4
//   (thread_proc) index = 5
//   (thread_proc) index = 6
//   (thread_proc) index = 7
//   (thread_proc) index = 8
//   (thread_proc) index = 9
 
// This code can produce the following output if `thread1` is created with std::jthread :
//
// (main) begin
//   (thread_proc) index = 0
//   (thread_proc) index = 1
//   (thread_proc) index = 2
//   (thread_proc) index = 3
//   (thread_proc) index = 4
//   (thread_proc) index = 5
//   (thread_proc) index = 6
//   (thread_proc) index = 7
//   (thread_proc) index = 8
//   (thread_proc) index = 9
// (main) end
 
// This code can produce the following output if `thread1` is created std::thread :
//
// (main) begin
// libc++abi: terminating

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::jthread_pool class to execute code on worker threads that are managed by the framework xrd.

An xtd::threading::jthread object is identical to an xtd::threading::thread whose xtd::threading::thread::auto_join property is set to true.

Cosntructors
	jthread (const xtd::threading::parameterized_thread_start &start)
	Initializes a new instance of the xtd::threading::jthread class, specifying a delegate that allows an object to be passed to the thread when the thread is started.
	jthread (const xtd::threading::parameterized_thread_start &start, int32 max_stack_size)
	Initializes a new instance of the xtd::threading::jthread 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.
	jthread (const xtd::threading::thread_start &start)
	Initializes a new instance of the xtd::threading::jthread class.
	jthread (const xtd::threading::thread_start &start, int32 max_stack_size)
	Initializes a new instance of the xtd::threading::jthread class, specifying the maximum stack size for the thread.

Public Static Methods
static jthread	start_new (const xtd::threading::thread_start &start)
	Create and immedialtely start a xtd::threading::jthread with specified method.
static jthread	start_new (const xtd::threading::parameterized_thread_start &start, std::any obj)
	Create and immedialtely start a xtd::threading::jthread with specified method.

Additional Inherited Members
Static Public Attributes inherited from xtd::threading::thread
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.
Public Member Functions inherited from xtd::threading::thread
	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.
bool	auto_join () const noexcept
	Gets a value indicating the current thread wiil be joined when destroyed.
thread &	auto_join (bool value)
	Sets a value indicating the current thread wiil be joined when destroyed.
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.
string	name () const noexcept
	Gets the name of the thread.
thread &	name (const string &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.
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 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::threading::thread
static thread &	current_thread () noexcept
	Gets the currently running thread.
static thread &	main_thread ()
	Gets the main thread.
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.
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

jthread() [1/4]

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

explicit

Initializes a new instance of the xtd::threading::jthread 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::jthread::start method. To pass a data object to the thread, use the xtd::threading::jthread::start(std::any) method overload.

jthread() [2/4]

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

Initializes a new instance of the xtd::threading::jthread 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::jthread::start method. To pass a data object to the thread, use the xtd::threading::jthread::start(std::any) method overload.

jthread() [3/4]

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

explicit

Initializes a new instance of the xtd::threading::jthread 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::jthread::start method.

jthread() [4/4]

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

Initializes a new instance of the xtd::threading::jthread 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::jthread::start method.

Member Function Documentation

start_new() [1/2]

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

static

Create and immedialtely start a xtd::threading::jthread 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.

start_new() [2/2]

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

static

Create and immedialtely start a xtd::threading::jthread 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.

---

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

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