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/xtd>
 
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());
  using_(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::thread_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 auto	start_new (const xtd::threading::thread_start &start) -> jthread
	Create and immedialtely start a xtd::threading::jthread with specified method.
static auto	start_new (const xtd::threading::parameterized_thread_start &start, const xtd::any_object &obj) -> jthread
	Create and immedialtely start a xtd::threading::jthread with specified method.

Additional Inherited Members
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.
	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.
auto	auto_join () const noexcept -> bool
	Gets a value indicating the current thread wiil be joined when destroyed.
auto	auto_join (bool value) -> thread &
	Sets a value indicating the current thread wiil be joined when destroyed.
auto	handle () const noexcept -> intptr
	Gets the native operating system handle.
auto	is_alive () const noexcept -> bool
	Gets a value indicating the execution status of the current thread.
auto	is_background () const noexcept -> bool
	Gets a value indicating whether or not a thread is a background thread.
auto	is_background (bool value) -> thread &
	Sets a value indicating whether or not a thread is a background thread.
auto	is_main_thread () const noexcept -> bool
	Gets a value indicating the current thread is the main thread.
auto	is_thread_pool_thread () const noexcept -> bool
	Gets a value indicating whether or not a thread belongs to the managed thread pool.
auto	joinable () const noexcept -> bool
	Gets a value indicating the current thread is joinable.
auto	managed_thread_id () const noexcept -> int32
	Gets a unique identifier for the current managed thread.
auto	name () const noexcept -> string
	Gets the name of the thread.
auto	name (const string &value) -> thread &
	Sets the name of the thread.
auto	priority () const noexcept -> xtd::threading::thread_priority
	Gets a value indicating the scheduling priority of a thread.
auto	priority (xtd::threading::thread_priority value) -> thread &
	Sets a value indicating the scheduling priority of a thread.
auto	processor_affinity () const noexcept -> const xtd::array< xtd::size > &
	Gets the processors on which the associated thread can run.
auto	processor_affinity (const xtd::array< xtd::size > &value) -> thread &
	Sets the processors on which the associated thread can run.
auto	thread_id () const noexcept -> intptr
	Gets the native operating system thread id.
auto	thread_state () const noexcept -> xtd::threading::thread_state
	Gets a value containing the states of the current thread.
auto	abort () -> void
	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.
auto	detach () -> void
	Sets the thread background.
auto	get_hash_code () const noexcept -> xtd::size override
	Serves as a hash function for a particular type.
auto	interrupt () -> void
	Interrupts a thread that is in the xtd::threading::thread_state::wait_sleep_join thread state.
auto	join () -> void
	Blocks the calling thread until this thread object terminates, while continuing to perform standard COM and SendMessage pumping.
auto	join (int32 milliseconds_timeout) -> bool
	Blocks the calling thread until this thread object terminates or the specified time elapses, while continuing to perform standard COM and SendMessage pumping.
auto	join (const time_span &timeout) -> bool
	Blocks the calling thread until this thread object terminates or the specified time elapses, while continuing to perform standard COM and SendMessage pumping.
auto	resume () -> void
	Resumes a thread that has been suspended (Should not be used).
auto	start () -> void
	Causes the operating system to change the state of the current instance to xtd::threading::thread_state::running.
auto	start (const xtd::any_object &obj) -> void
	Causes the operating system to change the state of the current instance to xtd::threading::thread_state::running.
auto	suspend () -> void
	Either suspends the thread, or if the thread is already suspended, has no effect (Should not be used).
	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 type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const
	Returns a xtd::string that represents the current object.
static auto	current_thread () noexcept -> thread &
	Gets the currently running thread.
static auto	main_thread () -> thread &
	Gets the main thread.
static auto	start_new (const xtd::threading::thread_start &start) -> thread
	Create and immedialtely start a xtd::threading::thread with specified method.
static auto	start_new (const xtd::threading::parameterized_thread_start &start, const xtd::any_object &obj) -> thread
	Create and immedialtely start a xtd::threading::thread with specified method.
static auto	join_all () -> void
	Blocks the calling thread until all joinable threads terminate.
static auto	join_all (int32 milliseconds_timeout) -> bool
	Blocks the calling thread until all joinable threads terminate or the specified time elapses, while continuing.
static auto	join_all (const time_span &timeout) -> bool
	Blocks the calling thread until all joinable threads terminate or the specified time elapses, while continuing.
template<class collection_t>
static auto	join_all (const collection_t &threads) -> void
	Blocks the calling thread until all specified joinable threads collection terminate.
template<class collection_t>
static auto	join_all (const collection_t &threads, int32 milliseconds_timeout) -> bool
	Blocks the calling thread until all specified joinable threads collection terminate or the specified time elapses, while continuing.
template<class collection_t>
static auto	join_all (const collection_t &threads, const time_span &timeout) -> bool
	Blocks the calling thread until all specified joinable threads collection terminate or the specified time elapses, while continuing.
static auto	sleep (int32 milliseconds_timeout) -> void
	Suspends the current thread for a specified time.
static auto	sleep (const time_span &timeout) -> void
	Suspends the current thread for a specified time.
static auto	spin_wait (int32 iterations) -> void
	Causes a thread to wait the number of times defined by the iterations parameter.
static auto	yield () noexcept -> bool
	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.
template<class object_a_t, class 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<class object_a_t, class 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(const xtd::any_object&) 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(const xtd::any_object&) 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]

auto xtd::threading::jthread::start_new ( const xtd::threading::thread_start & start ) -> jthread

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]

auto xtd::threading::jthread::start_new ( const xtd::threading::parameterized_thread_start & start, const xtd::any_object & obj ) -> jthread

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.hpp