|
|
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).
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).
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).
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.
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).
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.
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).
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).
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).
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).
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).
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.
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.
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
Automata Creation
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.
Macros
-
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).
|