NAME

fttl_thread_create - Creates a thread within a task, allocates CPU for its execution on a timeline schedule, sets its state, and its scheduling parameters.

LIBRARY

#include rt/rt_thread.h

SYNOPSIS

kern_return_t fttl_thread_create(parent_task, new_thread, thread_attr)
task_t parent_task;
thread_t *new_thread;
rt_thread_attr_t thread_attr;

DESCRIPTION

The fttl_thread_create function creates a new timeline thread within the parent_task. The attributes of the new thread are specified by thread_attr which must be initialized using fttl_thread_attribute_init. The three times, ready, execution and deadline specified in thread_attr are used by the timeline scheduler to guarantee that the thread will receive execution units of CPU time between its ready time and its deadline. A dlh_port which should be initialized using rt_thread_deadline_handler, is also specified in thread_attr. A message will be sent to this port if the thread executes beyond its deadline.

If the isPersistent flag is TRUE the thread created by fttl_thread_create will not be submitted to the scheduler immediately. Instead a persistent thread will be created and the ready, execution and deadline times will be ignored. A subsequent call to fttl_activate_persist_thread is required to schedule an instance of a persistent thread. If the isPersistent flag is FALSE the new thread is immediately scheduled according to the time specifications in thread_attr.

If the isFT flag is TRUE the thread created by fttl_thread_create will be fault tolerant. The scheduler will guarantee that this thread will be allowed enough time to re-execute if the first instance fails. The thread will re-execute only if the fault_flag is TRUE when the thread exits (see fttl_set_fault_flag). If the isFT flag is FALSE the thread created by fttl_thread_create will not be fault tolerant, no automatic re-execution will occur and the fault_flag will be ignored. A thread may be removed from the timeline by using the thread_terminate system call.

The new thread holds all the same resources and state as a thread which is created using thread_create. Additionally, new_thread has its execution state and scheduling parameters set to the values in thread_attr. Also, threads created using fttl_thread_create can have a deferred execution time (using the start_time field in thread_attr). The format of fttl_thread_attr is specified in . At the end of the execution of a fault-tolerant thread, (isFT = TRUE), a system fault_flag is checked and if set causes the thread to be re-executed. The fault_flag can be set by calling fttl_set_fault_flag. If at most one thread is re-executed every fault_interval (see set_fttl_schedule_policy), then fttl_thread_create guaran- tees that the thread's re-execution will complete within its deadline.

PARAMETERS

parent_task The id of the task that is to contain the new thread.
new_thread [out] The kernel-assigned id for the new thread.
thread_attr The scheduling and state parameters for the new thread.

RETURN VALUE

KERN_SUCCESS A new thread has been created and its state and scheduling parameters have been set.
KERN_INVALID_ARGUMENT parent_task is not a valid task.
KERN_INVALID_VALUE thread_attr contains an invalid value.
KERN_RESOURCE_SHORTAGE Some critical kernel resource is not available. For example there is not enough memory, or the thread and its re-execution cannot be guaranteed to complete by the deadline.

RELATED INFORMATION

Functions:

rt_thread_exit, thread_create, thread_terminate, thread_get_attribute, thread_set_attribute, fttl_thread_attribute_init, rt_set_scheduling_policy fttl_set_fault_flag, fttl_set_fault_interval, fttl_activate_persist_thread. fttl_instance_self, fttl_deactivate_persist_thread.