NAME

fttl_thread_attribute_init - Creates a fttl_thread attribute template

LIBRARY

#include

SYNOPSIS

kern_return_t fttl_thread_attribute_init(st_time, ex_time, de_time, entry, arg, port, thread_attr)
timespec_t st_time;
timespec_t ex_time;
timespec_t de_time;
boolean_t isPersistent;
boolean_t isFT;
void (*entry)();
int *arg;
mach_port_t *dlh_port;
fttl_thread_attr_t *thread_attr;

DESCRIPTION

The fttl_thread_attribute_init library function creates a rt_thread_attr_data_t template from the arguments earliest start time, execution time, deadline, isPersistent, isFT, entry, arg, and dlh_port, and returns the template in thread_attr. This template is meant to be used with fttl_thread_create, and is intended to streamline the most common cases. fttl_thread_attribute_init also takes care of allocating memory for a new thread's stack and wiring it down, as well as taking care of port rights for deadline expiration ports. Note that fttl_thread_attribute_init sets a thread's aperiodic attributes.

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 submitted to the scheduler immediately by the fttl_thread_create call.

If the isFT flag is TRUE, the thread created by fttl_thread_create will be fault tolerant. The scheduler will guarantee that, when scheduled, 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.

Dlh_port is used to specify a port which will receive a message if the thread overruns its deadline. It should be initialized using rt_thread_deadline_handler. If no deadline handler is required, dlh_port must be zero. The timeline scheduler includes a default deadline handler which protects the system from erroneous user threads. Before the thread starts execution for the first time the deadline timer is set to alarm at st_time + ex_time. If this timer expires, i.e. the thread overruns its execution time, the default deadline handler is called. If the thread is fault-tolerant and the user has created a deadline handler, the deadline timer is reset to st_time + 2 * ex_time before the user's deadline handler is called. The user has three options to choose from in the deadline handler. The thread can be terminated by thread_terminate, it can be continued from its current state by thread_resume or it can be restarted by setting the fault_flag TRUE, fttl_set_fault_flag and calling thread_terminate. In any case the user has ex_time time units before the deadline timer expires a second time. If the thread is not fault-tolerant or if there is no user deadline handler or if the deadline timer expires a second time the default deadline handler automatically terminates the thread without notifying the user. This prevents corruption of the timeline due to erroneous timeline threads or deadline handlers.

PARAMETERS

st_time, ex_time, de_time The start time, execution time and deadline of the new thread.
isPersistent The new thread will be persistent.
isFT The new thread will be fault tolerant.
entry The entry point for the new thread.
arg The argument to be passed to the new thread.
dlh_port [out] The port which will receive expiration messages in case of an overrun task, that is, a task that executes for longer than ex_time. Dlh_port must be zero if no deadline handler is defined.
thread_attr [out] The filled-in rt_thread_attr_t template.

RETURN VALUE

KERN_SUCCESS thread_attr structure has been filled with the correct values, and the stack and ports have been properly allocated.
KERN_INVALID_ARGUMENT The timespec_t described by st_time, ex_time or de_time are not legal. Common causes include using a nsecs value over or equal to a second.
OTHER_ERRORS If vm_allocate, vm_wire, mach_port_allocate, or mach_port_insert_right fail, then their errors are passed back.

RELATED INFORMATION

Functions:

thread_create, rt_thread_deadline_handler, rt_thread_exit, thread_get_attribute, thread_set_attribute, rt_set_scheduling_policy, fttl_thread_create, fttl_set_fault_flag, fttl_set_fault_interval, fttl_activate_persist_thread, fttl_instance_self, fttl_deactivate_persist_thread.