NAME

fttl_add_to_template - Creates a periodic thread within a task, and schedules it on a timeline template.

SYNOPSIS

kern_return_t fttl_add_to_template(parent_task, new_thread, thread_attr template)
task_t parent_task;
thread_t *new_thread;
rt_thread_attr_t thread_attr;
ft_template_t template;

DESCRIPTION

The fttl_add_to_template function creates a new periodic 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 ready, and deadline times in thread_attr are treated as offsets from the start of the tem- plate. The first instance of the periodic thread will be scheduled on the template between ready and deadline. The period specified in thread_attr is added to ready and deadline to find when to schedule subsequent instances. i.e. The Nth instance will be between ready + (N - 1) * period and deadline + (N - 1) * period.

The same algorithim is used to schedule instances on the template as is used to schedule threads on the timeline. The scheduler keeps inserting instances until deadline + (N - 1) * period be- comes greater than the length of the template. Each instance is guaranteed execution units of CPU time between its ready time and its deadline. If an attempt to schedule an instance fails all in- stances of the thread are removed from the template and an error (KERN_RESOURCE_SHORTAGE) is returned to the application.

Periodic timeline threads cannot be persistent. If the isPer- sistent flag is TRUE an error is returned to the application.

If the isFT flag is TRUE the thread created by fttl_add_to_template will be fault tolerant. The scheduler will guarantee that each instance of 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_add_to_template will not be fault tolerant, no automatic re-execution will occur and the fault_flag will be ignored.

A dlh_port which should be initialized using rt_thread_deadline_handler, may also be specified in thread_attr. A message will be sent to this port if the thread is fault- tolerant and it executes beyond the end of its execution time start + execution. The application's deadline handler may choose to restart, resume or terminate the instance. If there is no user deadline handler for the faulty instance or if the thread is not fault-tolerant the instance will be terminated by the kernel without sending notification to the application. If the restart- ed or resumed instance also exceeds its execution time it will be terminated by the kernel without sending further notification to the application.

A thread may be removed from the template by using the fttl_remove_from_template or the fttl_clear_template 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. The format of fttl_thread_attr is speci- fied 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 then fttl_add_to_template guarantees 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.
template Specifies a template previously created by fttl_create_template or the default template, (template = NULL).

RETURN VALUE

KERN_SUCCESS A new periodic timeline thread has been created and one or more instances have been scheduled on the specified tem- plate.
KERN_INVALID_ARGUMENT Either parent_task or template is invalid. timeline thread.
KERN_INVALID_VALUE contains an invalid value e.g. isPersistent flag is TRUE.
KERN_RESOURCE_SHORTAGE Some critical kernel resource is not available. For example there is not enough memory, or all the thread instances and their re- executions cannot be guaranteed to complete by their deadlines.

RELATED INFORMATION

Functions:

rt_thread_exit, thread_create, thread_terminate, thread_get_attribute, thread_set_attribute, fttl_thread_create, fttl_thread_attribute_init, rt_set_scheduling_policy, fttl_set_fault_flag, fttl_set_fault_interval, fttl_activate_persist_thread, fttl_enable_periodic, fttl_disable_periodic, fttl_create_template, fttl_activate_template, fttl_add_to_template, fttl_remove_from_template, fttl_clear_template. fttl_get_template_length.