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 `n`th 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 Tue Jun 4 10:09:20 2002