core/thread

thread

Types

Pool :: struct {
	allocator:         mem.Allocator,
	mutex:             sync.Mutex,
	sem_available:     sync.Sema,
	// the following values are atomic
	num_waiting:       int,
	num_in_processing: int,
	num_outstanding:   int,
	num_done:          int,
	// end of atomics
	// called once per thread at startup
	thread_init_proc:  Thread_Init_Proc,
	thread_init_data:  rawptr,
	// called once per thread at shutdown
	thread_fini_proc:  Thread_Fini_Proc,
	thread_fini_data:  rawptr,
	is_running:        bool,
	threads:           []^Thread,
	tasks:             queue.Queue(Task),
	tasks_done:        [dynamic]Task,
}

Source

Do not access the pool's members directly while the pool threads are running, since they use different kinds of locking and mutual exclusion devices. Careless access can and will lead to nasty bugs. Once initialized, the pool's memory address is not allowed to change until it is destroyed.

Pool_Thread_Data :: struct {
	pool: ^Pool,
	task: Task,
}

Source

Task :: struct {
	procedure:  Task_Proc,
	data:       rawptr,
	user_index: int,
	allocator:  mem.Allocator,
}

Source

Task_Proc :: proc(task: Task)Source

Thread :: struct {
	specific:           Thread_Os_Specific,
	flags:              bit_set[Thread_State; u8],
	// Thread ID. Depending on the platform, may start out as 0 (zero) until the thread
	// has had a chance to run.
	id:                 int,
	// The thread procedure.
	procedure:          Thread_Proc,
	// User-supplied pointer, that will be available to the thread once it is
	// started. Should be set after the thread has been created, but before
	// it is started.
	data:               rawptr,
	// User-supplied integer, that will be available to the thread once it is
	// started. Should be set after the thread has been created, but before
	// it is started.
	user_index:         int,
	// User-supplied array of arguments, that will be available to the thread,
	// once it is started. Should be set after the thread has been created,
	// but before it is started.
	user_args:          [8]rawptr,
	// The thread context.
	// This field can be assigned to directly, after the thread has been
	// created, but __before__ the thread has been started. This field must
	// not be changed after the thread has started.
	// 
	// **Note**: If this field is **not** set, the temp allocator will be managed
	// automatically. If it is set, the allocators must be handled manually.
	// 
	// **IMPORTANT**:
	// By default, the thread proc will get the same context as `main()` gets.
	// In this situation, the thread will get a new temporary allocator which
	// will be cleaned up when the thread dies. ***This does NOT happen when
	// `init_context` field is initialized***.
	// 
	// If `init_context` is initialized, and `temp_allocator` field is set to
	// the default temp allocator, then `runtime.default_temp_allocator_destroy()`
	// procedure needs to be called from the thread procedure, in order to prevent
	// any memory leaks.
	init_context:       Maybe(runtime.Context),
	// The allocator used to allocate data for the thread.
	creation_allocator: mem.Allocator,
}

Source

Type representing a thread handle and the associated with that thread data.

Thread_Fini_Proc :: proc(thread: ^Thread, user_data: rawptr)Source

Thread_Init_Proc :: proc(thread: ^Thread, user_data: rawptr)Source

Thread_Os_Specific :: struct {}Source

Thread_Os_Specific :: struct {
	unix_thread: posix.pthread_t,
	start_ok:    sync.Sema,
}

Source

NOTE(tetra): Aligned here because of core/unix/pthread_linux.odin/pthread_t. Also see core/sys/darwin/mach_darwin.odin/semaphore_t.

Thread_Priority :: enum int {
	Normal = 0,
	Low    = 1,
	High   = 2,
}

Source

Type representing priority of a thread.

Thread_Proc :: proc(^Thread)Source

Type for a procedure that will be run in a thread, after that thread has been started.

Thread_State :: enum u8 {
	Started      = 0,
	Joined       = 1,
	Done         = 2,
	Self_Cleanup = 3,
}

Source

Type representing the state/flags of the thread.

Constants

IS_SUPPORTED :: _IS_SUPPORTEDSource

Value, specifying whether core:thread functionality is available on the current platform.

MAX_USER_ARGUMENTS :: 8Source

Maximum number of user arguments for polymorphic thread procedures.

_IS_SUPPORTED :: falseSource

_IS_SUPPORTED :: trueSource

Variables

_thread_priority_map :: [3]i32 = [Thread_Priority]i32{
	.Normal = 0,
	.Low = -2,
	.High = +2,
}

Source

Procedures

_create :: proc(procedure: Thread_Proc, priority = Thread_Priority.Normal) -> (^Thread)Source

_create :: proc(procedure: Thread_Proc, priority: Thread_Priority) -> (^Thread)Source

Creates a thread which will run the given procedure. It then waits for start to be called.

_destroy :: proc(thread: ^Thread)Source

_destroy :: proc(t: ^Thread)Source

_is_done :: proc(t: ^Thread) -> (bool)Source

_join :: proc(t: ^Thread)Source

_join_multiple :: proc(threads)Source

_maybe_destroy_default_temp_allocator :: proc(init_context: Maybe(runtime.Context))Source

_select_context_for_thread :: proc(init_context: Maybe(runtime.Context)) -> (runtime.Context)Source

_start :: proc(t: ^Thread)Source

_terminate :: proc(thread: ^Thread, exit_code: int)Source

_terminate :: proc(t: ^Thread, exit_code: int)Source

_yield :: proc()Source

create :: proc(procedure: Thread_Proc, priority = Thread_Priority.Normal) -> (^Thread)Source

Create a thread in a suspended state with the given priority.

This procedure creates a thread that will be set to run the procedure specified by procedure parameter with a specified priority. The returned thread will be in a suspended state, until start() procedure is called.

To start the thread, call start(). Also the create_and_start() procedure can be called to create and start the thread immediately.

create_and_start :: proc(fn: proc(), init_context: Maybe(runtime.Context), priority = Thread_Priority.Normal, self_cleanup: untyped boolean = false) -> (t: ^Thread)

Source

Run a procedure on a different thread.

This procedure runs the given procedure on another thread. The context specified by init_context will be used as the context in which fn is going to execute. The thread will have priority specified by the priority parameter.

If self_cleanup is specified, after the thread finishes the execution of the fn procedure, the resources associated with the thread are going to be automatically freed.