Home:	Fair Threads in C
Previous chapter:	Conclusion
Next chapter:

DESCRIPTION

ft_scheduler_create returns a new scheduler that will run the threads created in it, using ft_thread_create. The new scheduler sched starts running when the function ft_scheduler_start is called.

RETURN VALUES

On success ft_scheduler_create returns the new scheduler; NULL is returned otherwise. On success the value 0 is returned by ft_scheduler_start and a non-zero error code is returned otherwise.

ERRORS

NULL

The scheduler cannot be created.

BADCREATE

The scheduler sched is not correctly created when started.

SEE ALSO

ft_thread_create (3).

DESCRIPTION

ft_thread_create returns a new thread of control and links it to the scheduler sched. While linked in sched, the new thread will execute concurrently with the other threads linked in it. Actual starting of the new thread is asynchronous with the creation. The new thread applies the function runnable passing it args as first argument. The new thread terminates when it executes ft_exit or when it returns from the runnable function.

When stopped (by ft_scheduler_stop), the new thread applies the function cleanup, if it is not NULL, passing it args as first argument.

A pthread is created with each fair thread. This pthread is initially attached. It can be detached using ft_pthread and pthread_detach.

RETURN VALUES

On success, ft_thread_create returns a new thread; NULL is returned otherwise.

ERRORS

NULL

The thread cannot be created, or the scheduler sched is not correctly created.

SEE ALSO

ft_exit (3), ft_scheduler_create (3), ft_scheduler_stop (3), ft_pthread (3).

DESCRIPTION

ft_event_create returns a new event which is created in the scheduler sched. The event can be generated by ft_event_generate or ft_scheduler_broadcast, and it can awaited by ft_event_await.

RETURN VALUES

On success, the new event is returned and set to absent; NULL is returned otherwise.

ERRORS

NULL

The event cannot be created or the scheduler sched is not correctly created.

SEE ALSO

ft_event_generate (3), ft_scheduler_broadcast (3), ft_event_await (3).

DESCRIPTION

ft_scheduler_stop asks the scheduler running the thread th to force termination of it. Nothing special happens if the thread is already terminated. Otherwise, at the begining of the next instant, th executes the function cleanup if it exists, or otherwise terminates immediately.

ft_scheduler_suspend asks the scheduler running the thread th to suspend execution of it. The suspension will become actual at the beginning of the next instant of the scheduler.

ft_scheduler_resume asks the scheduler running the thread th to resume execution of it. The resume will become actual at the beginning of the next instant of the scheduler. Suspension has higher priority than resume: if a thread is suspended and resumed during the same instant, then the thread will be suspended. A suspended thread which is stopped is first resumed.

RETURN VALUES

On success, the value 0 is returned. On error, a non-zero error code is returned.

ERRORS

BADCREATE

The thread th is not correctly created.

BADLINK

The thread th is unlinked.

BADMEM

Not enough memory (the order cannot be stored by the scheduler).

SEE ALSO

ft_thread_create (3), ft_scheduler_create (3).

DESCRIPTION

ft_scheduler_broadcast asks the scheduler of the event evt to broadcast it. The event will be generated during the next instant of the scheduler. The value val is associated to evt when the function ft_scheduler_broadcast_value is used.

RETURN VALUES

On success, the value 0 is returned. On error, a non-zero error code is returned.

ERRORS

BADCREATE

The event evt is not correctly created.

BADMEM

Not enough memory (the scheduler cannot store the broadcast order).

SEE ALSO

ft_event_create (3).

DESCRIPTION

ft_thread_cooperate makes the calling thread cooperate by returning the control to the scheduler in which it is running. The call ft_thread_cooperate_n (k) is equivalent to for (i=0;i<k;i++) ft_thread_cooperate ().

RETURN VALUES

On success, the value 0 is returned. On error, a non-zero error code is returned.

ERRORS

BADLINK

The calling thread is unlinked.

DESCRIPTION

ft_thread_join suspends the execution of the calling thread until the thread th terminates (either by reaching the end of the function it run, or by executing ft_exit) or is stopped (by ft_scheduler_stop). If th is already terminated, the call immediately terminates. ft_thread_join_n (th,i) waits for at most i instants for termination of th.

RETURN VALUES

On success, the value 0 is returned. On error, a non-zero error code is returned.

ERRORS

BADCREATE

The thread th is not correctly created.

BADLINK

The calling thread is unlinked.

TIMEOUT

The timeout is reached before the thread is joined.

SEE ALSO

ft_thread_create (3), ft_exit (3), ft_scheduler_stop (3).

DESCRIPTION

ft_thread_generate generates the event evt for the current instant of the scheduler in which the calling thread is running. The event is thus present for this instant; it will be automatically reset to absent at the begining of the next instant. The value val is associated to evt when ft_thread_generate_value is used.

ft_thread_await suspends the calling thread until evt becomes generated in the scheduler in which it is running. The waiting takes as many instants as the generation of evt takes. ft_thread_await_n (evt,k) is similar to ft_thread_await (evt) except that the waiting of evt lasts at most k instants.

ft_thread_select suspends the calling thread until one element of array becomes generated in the scheduler in which the thread is running; array should be of length k. On resumption, mask which is an array of k integers, is set accordingly: mask[i] is 1 if array[i] was generated; mask[i] is 0, otherwise. ft_thread_select_n (k,array,mask,p) is similar to ft_thread_select (k,array,mask) except that the waiting lasts at most p instants.

RETURN VALUES

On success the value 0 is returned and a non-zero error code is returned on error.

ERRORS

BADCREATE

The exist an event (either evt or an element of array) which is not correctly created.

BADLINK

Either the calling thread is unlinked, or the scheduler of the calling thread and the one of a considered event (evt or an element of array) are different.

BADMEM

Not enough memory (can only occur with ft_thread_generate_value).

TIMEOUT

The timeout is reached.

SEE ALSO

ft_event_create (3), ft_thread_get_value (3).

DESCRIPTION

ft_thread_get_value returns the nth value associated during the current instant to the event evt through calls of ft_event_generate_value or ft_scheduler_broadcast_value. If such a value exists, ft_thread_get_value sets result with a reference to it and terminates immediately (that is, during the current instant). Otherwise, it terminates at the next instant (returning NEXT) and result is then set to NULL.

RETURN VALUES

On success, the value 0 is returned (during the current instant). Otherwise, a non-zero error code is returned.

ERRORS

BADCREATE

The event evt is not correctly created.

BADLINK

Either the calling thread is unlinked, or the scheduler of the calling thread and the one of evt are different.

NEXT

Less than n values where actually associated to generations of evt during the previous instant.

SEE ALSO

ft_thread_generate_value (3), ft_scheduler_broadcast_value (3).

DESCRIPTION

ft_thread_unlink unlinks the calling thread from the scheduler which is running it. Execution of the thread suspends until the begining of the next instant of the scheduler. At that point, the thread turns into a standard thread, not linked to any scheduler, and it resumes execution autonomously. Initialy, a fair thread is automatically linked to the scheduler in which it is created (by ft_thread_create). ft_thread_link links the calling thread to the scheduler sched. The thread must be unlinked. Execution suspends until sched gives the control to the thread; then, the thread resumes execution, being scheduled by sched.

RETURN VALUES

On success, the value 0 is returned. On error, a non-zero error code is returned.

ERRORS

BADCREATE

The scheduler sched is not correctly created.

BADLINK

The calling thread is already linked while running ft_thread_link, or it is unlinked while running ft_thread_unlink.

BADMEM

Not enough memory (the scheduler cannot store the link/unlink order).

SEE ALSO

ft_thread_create (3).

DESCRIPTION

ft_thread_self returns the calling thread. ft_thread_scheduler returns the scheduler of the calling thread.

ERRORS

The value NULL is returned by ft_thread_self when the calling thread is not correctly created, or by ft_thread_scheduler when the calling thread is not correctly created or is unlinked.

DESCRIPTION

For unlinked threads, ft_thread_mutex_lock is like pthread_mutex_lock and ft_thread_mutex_unlock is like pthread_mutex_unlock.

For linked threads, ft_thread_mutex_lock suspends the calling thread until mutex can be locked. Thus, while mutex is unavailable, other threads in the scheduler can continue to run (this would not be the case if pthread_mutex_lock where used instead of ft_thread_mutex_lock). All locks owned by a thread are automatically released when it terminates or when it is stopped.

RETURN VALUES

On success ft_thread_mutex_lock and ft_thread_mutex_unlock both return the value 0. On error, a non-zero error code is returned.

ERRORS

Errors returned are the ones returned by pthread_mutex_lock and pthread_mutex_unlock.

SEE ALSO

ft_thread_link (3), ft_thread_unlink (3).

DESCRIPTION

ft_exit forces the calling thread to terminate.

RETURN VALUES

The function ft_exit never returns.

DESCRIPTION

The function ft_pthread returns the pthread on which the fair thread thread is built.

DESCRIPTION

• AUTOMATON(name) declares the automaton name.
• DEFINE_AUTOMATON(name) starts definion of the automaton name.
• BEGIN_AUTOMATON starts the state list.
• END_AUTOMATON ends the state list.
• STATE(num) starts state num description. States must be numbered consecutively, starting from 0. State 0 is the initial state.
• STATE_AWAIT(num,event) awaits event. It is the counterpart of ft_thread_await for automata. Execution stays in this state until event is generated.
• STATE_AWAIT_N(num,event,n) awaits event during at most n instant. It is the counterpart of ft_thread_await_n.
• STATE_GET_VALUE(num,event,n,result) is used to get the nth value generated with event. It is the counterpart of ft_thread_get_value.
• STATE_JOIN(num,thread) is used to join thread. It is the counterpart of ft_thread_join.
• STATE_JOIN_N(num,thread,n) is an attempt to join thread during at most n instants. It is the counterpart of ft_thread_join_n.
• STATE_STAY(num,n) let the automaton stay for n instants in the state.
• STATE_SELECT(num,k,array,mask) awaits elements of array which is an array of events of length k. It is the counterpart of ft_thread_select for automata. Execution stays in this state until at least one element of array is generated; the presence of events is recorded in mask which is an array of integers of length k.
• STATE_SELECT_N(num,k,array,mask,n) awaits elements of array during at most n instant. It is the counterpart of ft_thread_select_n.
• GOTO(num) blocks execution for the current instant and sets the state to be executed at the next instant to be state num.
• GOTO_NEXT blocks execution for the current instant and sets the state for the next instant to be the next state.
• IMMEDIATE(num) forces execution to jump to state n which is immediately (that is, during the same instant) executed.
• RETURN forces immediate termination of the automaton.
• SELF is the automaton. It is of type ft_thread_t.
• LOCAL is the local data of the automaton. The local data is of type void*.
• SET_LOCAL(data) sets the local data of the automaton.
• ARGS is the argument that is passed at creation to the automaton. It is of type void*.
• RETURN_CODE is the error code set by macros run by the automaton. As usual, 0 means success.

RETURN VALUES

On success, ft_automaton_create returns a new thread; NULL is returned otherwise.

ERRORS

NULL

The automaton cannot be created, or the scheduler sched is not correctly created.

EXAMPLE

The following automaton switches control between two threads, according to the presence of an event.

DEFINE_AUTOMATON(switch_aut)
{
   void **args = ARGS;
   
   ft_event_t   event   = args[0]
   ft_thread_t  thread1 = args[1]
   ft_thread_t  thread2 = args[2]
   
  BEGIN_AUTOMATON
     
     STATE(0)
     {
        ft_scheduler_resume (thread1);
     }
     STATE_AWAIT (1,event)
     {
        ft_scheduler_suspend (thread1);
        ft_scheduler_resume  (thread2);
        GOTO(2);
     }
     STATE_AWAIT (2,event)
     {
        ft_scheduler_suspend (thread2);
        ft_scheduler_resume  (thread1);
        GOTO(1);
     }
     
  END_AUTOMATON
}

SEE ALSO

ft_thread_create (3), ft_thread_await (3), ft_thread_get_value (3), ft_thread_join (3).