8. Man Pages

8. Man Pages

Browsing

Home: Fair Threads in C

Previous chapter: Conclusion
Next chapter:


Man Pages

8.1 ft_scheduler_create
8.2 ft_thread_create
8.3 ft_event_create
8.4 ft_scheduler_stop
8.5 ft_scheduler_broadcast
8.6 ft_thread_cooperate
8.7 ft_thread_join
8.8 ft_thread_generate
8.9 ft_thread_get_value
8.10 ft_thread_link
8.11 ft_thread_self
8.12 ft_thread_mutex_lock
8.13 ft_exit
8.14 ft_pthread
8.15 ft_automaton_create


Chapters

1. Introduction
2. Rationale
3. API Overview
4. API
5. Examples
6. Related Work
7. Conclusion
8. Man Pages


8.1 ft_scheduler_create

SYNOPSIS

#include <fthread.h>

ft_scheduler_t ft_scheduler_create (void);

int ft_scheduler_start (ft_scheduler_t sched);


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).



8.2 ft_thread_create

SYNOPSIS

#include <fthread.h>

ft_thread_t ft_thread_create (ft_scheduler_t sched,
                              void (*runnable)(void*),
                              void (*cleanup)(void*),                     
                              void *args);


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).



8.3 ft_event_create

SYNOPSIS

#include <fthread.h>

ft_event_t ft_event_create (ft_scheduler_t sched);


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).



8.4 ft_scheduler_stop

SYNOPSIS

#include <fthread.h>

int ft_scheduler_stop    (ft_thread_t th);

int ft_scheduler_suspend (ft_thread_t th);

int ft_scheduler_resume  (ft_thread_t th);


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).



8.5 ft_scheduler_broadcast

SYNOPSIS

#include <fthread.h>

int ft_scheduler_broadcast       (ft_event_t evt);

int ft_scheduler_broadcast_value (ft_event_t evt,void *val);


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).



8.6 ft_thread_cooperate

SYNOPSIS

#include <fthread.h>

int ft_thread_cooperate   (void);

int ft_thread_cooperate_n (int n);


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.



8.7 ft_thread_join

SYNOPSIS

#include <fthread.h>

int ft_thread_join   (ft_thread_t th);

int ft_thread_join_n (ft_thread_t th,int n);


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).



8.8 ft_thread_generate

SYNOPSIS

#include <fthread.h>

int ft_thread_generate       (ft_event_t evt);

int ft_thread_generate_value (ft_event_t evt,void *val);

int ft_thread_await          (ft_event_t evt);

int ft_thread_await_n        (ft_event_t evt,int n);

int ft_thread_select         (int len,ft_event_t *array,int *mask);

int ft_thread_select_n       (int len,ft_event_t *array,int *mask,int timeout);


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).



8.9 ft_thread_get_value

SYNOPSIS

#include <fthread.h>

int ft_thread_get_value (ft_event_t evt,int n,void **result);


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).



8.10 ft_thread_link

SYNOPSIS

#include <fthread.h>

int ft_thread_unlink (void);

int ft_thread_link   (ft_scheduler_t sched);


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).



8.11 ft_thread_self

SYNOPSIS

#include <fthread.h>

ft_thread_t    ft_thread_self      (void);

ft_scheduler_t ft_thread_scheduler (void);


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.



8.12 ft_thread_mutex_lock

SYNOPSIS

#include <fthread.h>

int ft_thread_mutex_lock   (pthread_mutex_t *mutex);

int ft_thread_mutex_unlock (pthread_mutex_t *mutex);


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).



8.13 ft_exit

SYNOPSIS

#include <fthread.h>

void ft_exit (void);


DESCRIPTION

ft_exit forces the calling thread to terminate.


RETURN VALUES

The function ft_exit never returns.



8.14 ft_pthread

SYNOPSIS

#include <fthread.h>

pthread_t ft_pthread (ft_thread_t thread);


DESCRIPTION

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



8.15 ft_automaton_create

SYNOPSIS

#include <fthread.h>

ft_thread_t ft_automaton_create (ft_scheduler_t sched,
                                 void (*automaton)(ft_thread_t),
                                 void (*cleanup)(void*),                     
                                 void *args);

AUTOMATON(name) 
DEFINE_AUTOMATON(name) 
BEGIN_AUTOMATON
END_AUTOMATON  

STATE(num)    
STATE_AWAIT(num,event) 
STATE_AWAIT_N(num,event,delay)
STATE_GET_VALUE(num,event,n,result) 
STATE_STAY(num,delay)               
STATE_JOIN(num,thread)              
STATE_JOIN_N(num,thread,delay)
STATE_SELECT(num,n,array,mask)              
STATE_SELECT_N(num,n,array,mask,delay)

GOTO(num) 
GOTO_NEXT 
IMMEDIATE(num)
RETURN

SELF   
SET_LOCAL(data) 
LOCAL   
ARGS  
RETURN_CODE 


DESCRIPTION

ft_automaton_create is very similar to ft_thread_create except that a new automaton is returned. The automaton does not have its own pthread to execute, but it is run by the one of the scheduler. The automaton applies the function automaton. Argument args can be accessed in the automaton definition with the macro ARGS.


  • 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.
Note that there is no counterpart of ft_thread_link and ft_thread_unlink for automata, as an automaton always remains linked to the scheduler in which it was created.



RETURN VALUES

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

When an error is encountered during execution of a macro, RETURN_CODE is set accordingly, with one of the error values BADMEM, TIMEOUT, NEXT, BADLINK, or BADCREATE.


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).




This page has been generated by
Scribe.
Last update Sun Jun 9 15:48:08 2002