class::sys::Thread

class sys::Thread
  : public api::WorkObject

This class creates and manages new threads using POSIX calls.

Before creating the thread, the attributes should be set using:

Once the thread is running the scheduling policy can be updated using:

  • set_priority()

    static void thread_execute(void * args);
    
    Thread t; //default 4096 stack size and detached = true
    
    t.set_stacksize(2048);
    t.set_detachstate(Thread::JOINABLE);
    
    //calling get_policy() or get_priority() before thread is created will return an error
    
    t.create(thread_execute);
    
    t.set_priority(5, Sched::RR); //priority 5 round robin scheduling
    
    //now that the thread is running, the stacksize and detachstate cannot be changed
    
    printf("Thread policy is %d\n", t.get_policy());
    printf("Thread priority is %d\n", t.get_priority());
    printf("Thread stacksize is %d\n", t.get_stacksize());
    printf("Thread is joinable? %d\n", t.is_joinable());
    

Summary

Thread(

const arg::ThreadStackSize & stacksize,
const arg::IsDetached detached
)

~Thread()

const pthread_attr_t & attr() const

int create(

arg::ThreadFunction func,
arg::ThreadFunctionArgument args,
const arg::SchedulerPriority prio,
enum Sched::policy policy
)

int get_detachstate() const

int get_policy() const

int get_priority() const

int get_stacksize() const

pthread_t id() const

bool is_joinable() const

bool is_running() const

bool is_valid() const

int join(

arg::ThreadReturn value_ptr
) const

int kill(

const arg::SignalNumber sig
)

int set_detachstate(

enum detach_state value
)

int set_priority(

const arg::SchedulerPriority prio,
enum Sched::policy policy
)

int set_stacksize(

int size
)

int wait(

arg::ThreadReturn ret,
const arg::DelayInterval interval
) const

static pid_t get_pid()

static int join(

const arg::ThreadId ident,
arg::ThreadReturn value_ptr
)

static int join(

const arg::ThreadToJoin thread_to_join,
arg::ThreadReturn value_ptr
)

static pthread_t self()

static void yield()

enum detach_state

typedef void ( handler_function_t

enum thread_flags

Members

Thread(

const arg::ThreadStackSize & stacksize,
const arg::IsDetached detached
)

Constructs a new thread object.

Parameters

  • stack_size The stack size of the new thread (default is 4096)

  • detached Whether to create as a detached thread. If this value is false, another thread must use join() in order for the thread to terminate correctly.


~Thread()

const pthread_attr_t & attr() const

Allows read only access to the thread attributes.


int create(

arg::ThreadFunction func,
arg::ThreadFunctionArgument args,
const arg::SchedulerPriority prio,
enum Sched::policy policy
)

Starts the thread.

Parameters

  • func The function to execute as a new thread

  • args The arguments to pass to the new thread

  • prio The priority to set for the new thread

  • policy The new thread’s scheduling policy

Returns

Zero on success

This method creates a new thread. The Thread object only manages one thread at a time. To create multiple threads, you will need multiple instances of the Thread object.

Use the following methods to change thread attributes:


int get_detachstate() const

Gets the detach state (Thread::JOINABLE or Thread::DETACHED).


int get_policy() const

Get the thread policy.

Calling this method before the thread is created will return an error.


int get_priority() const

Gets the thread priority.

Calling this method before the thread is created will return an error.


int get_stacksize() const

Gets the stacksize.

This method will return zero if the stack size could not be retrieved. The error_number() method can be used to determine why.


pthread_t id() const

Gets the ID of the thread.


bool is_joinable() const

This method returns true if the thread is joinable


bool is_running() const

Checks if the thread is running.


bool is_valid() const

Returns true if the thread has a valid id.

If create() has not been called, this will return false. If there was an error creating the thread, this will also return false;


int join(

arg::ThreadReturn value_ptr
) const

Joins the calling thread to this object’s thread.

Parameters

  • value_ptr A pointer to where the return value of the thread function will be stored (ignored if null)

Returns

0 if joined, -1 if couldn’t join (doesn’t exist or is detached)

This method will block the calling thread until the thread function returns.


int kill(

const arg::SignalNumber sig
)

Sends a signal to the thread.

Parameters

  • sig The signal to send

Returns

Zero on success

This method sends a signal to the thread (equivalend to pthread_kill()). It causes the signal handler to be executed in the context of the thread, but the signal action will affect the whole process.

Thread t;

//create the thread

t.kill(0); //returns zero if the thread is valid but doesn't send a signal
t.kill(Signal::KILL); //will cause the entire process to die
t.kill(Signal::STOP); //will stop the thread from running

int set_detachstate(

enum detach_state value
)

Sets the detach state.

Parameters

  • value Detach state: use JOINABLE or DETACHED

This method must be called before calling create().


int set_priority(

const arg::SchedulerPriority prio,
enum Sched::policy policy
)

Sets the thread priority.

Parameters

  • prio Thread priority (higher value has higher priority)

  • policy Scheduling policy

Returns

Zero on success and less than zero for an error

This method must be called after calling create().


int set_stacksize(

int size
)

Sets the stacksize.

Parameters

  • size Stack size in bytes

This method must be called before calling create().


int wait(

arg::ThreadReturn ret,
const arg::DelayInterval interval
) const

Waits for the thread to complete (joins thread if it is not detached).

If the thread is joinable, this method will join the thread which blocks until the thread returns. If the thread is not-joinable, this method will poll is_running() until the thread completes.


static pid_t get_pid()

Returns the process ID of the calling thread.


static int join(

const arg::ThreadId ident,
arg::ThreadReturn value_ptr
)

Joins the calling thread to the specified thread.

Parameters

  • ident the ID of the target thread

  • value_ptr A pointer to the return value of the target thread

Returns

Zero on success

This method will block the calling thread until the joined thread returns.


static int join(

const arg::ThreadToJoin thread_to_join,
arg::ThreadReturn value_ptr
)

Joins the calling thread to the specified thread.

Parameters

  • thread A reference to the thread to joing

  • value_ptr a pointer to where the return value of thread will be stored

Returns

Zero on success

This method will block the calling thread until the joined thread returns.


static pthread_t self()

Returns the thread ID of the calling thread.


static void yield()

Yields the processor to another thread


enum detach_state
  • JOINABLE Joinable thread
  • DETACHED Detacthed thread

typedef void ( handler_function_t

Defines the function call type that is used to create() a new thread.


enum thread_flags
  • ID_ERROR ID is an error
  • ID_PENDING ID is ready to be created (not valid yet)

X

Thanks for Coming!

Subscribe to news and updates