timer.h File Reference

Use timeouts backed by signals and realtime clock. More...

#include <signal.h>
#include <stdbool.h>
#include <time.h>

Go to the source code of this file.

Data Structures
struct	o2s_timer_t

Macros
#define	O2sTimer
	Automatically delete the timer when going out of scope.
#define	ArmedTimer
	Automatically disarm the timer when going out of scope.

Functions
bool	o2s_timer_setup_process (void(*handle)(int, siginfo_t *, void *))
	Prepare the process for timeouts.
o2s_timer_t	o2s_timer_create (void)
	Initialize a timer, that will create a SIGALRM in the current thread when timing out.
o2s_timer_t	o2s_timer_start (o2s_timer_t timer, unsigned milliseconds)
	Arm timer for the specified duration, in milliseconds.
void	o2s_timer_stop (o2s_timer_t *timer)
	Disarm timer.
void	o2s_timer_delete (o2s_timer_t *timer)
	Destructor.

Detailed Description

Use timeouts backed by signals and realtime clock.

Copyright

2023, SAFRAN T4DS, ALL RIGHTS RESERVED

Author

Antoine GAGNIERE

Here is the intended usage of timers:

// In a given process
if (not o2s_timer_setup_process(some_signal_handler_that_tells_the_operation_to_exit))
    error();
 
{ // in a given thread
    O2sTimer timer = o2s_timer_create();
    if (!timer.created)
        error();
 
    { // Where a timeout is wanted
        ArmedTimer copy = o2s_timer_start();
        if (!copy.armed)
            error();
 
        some_operation_that_can_hang();
    } // <- the timer is disarmed here
 
    tell_the_operation_to_not_exit();
} // <- the timer is deleted here

Definition in file timer.h.

Macro Definition Documentation

ArmedTimer

#define ArmedTimer

Automatically disarm the timer when going out of scope.

In a situation where one wants to declare a timer in a local scope, this "typedef" can be used for that timer to be disarmed automatically when the variable goes out of scope.

It means this "typedef" can only be used like this:

{
    ArmedTimer copy = o2s_timer_start(my_timer, ...);
    ...
} // <- the timer will be disarmed at that point

Definition at line 67 of file timer.h.

O2sTimer

#define O2sTimer

Automatically delete the timer when going out of scope.

In a situation where one wants to declare a timer in a local scope, this "typedef" can be used for that timer to be deleted automatically when the variable goes out of scope.

It means this "typedef" can only be used like this:

{
    O2sTimer my_timer = o2s_timer_create(...);
    ...
} // <- the timer will be deleted at that point

Definition at line 50 of file timer.h.

Function Documentation

o2s_timer_create()

o2s_timer_t o2s_timer_create

(

void

)

Initialize a timer, that will create a SIGALRM in the current thread when timing out.

This needs to be done once per thread, as the goal is for the timer to interrupt the system calls of the current thread.

Returns

a timer object whose member created is false if it was unable to create the timer

Definition at line 59 of file timer.c.

o2s_timer_setup_process()

bool o2s_timer_setup_process

(

void(*

handle )(int, siginfo_t *, void *)

)

Prepare the process for timeouts.

Needed to be called only once, preferably before creating the threads.

Returns

true if successful, false otherwise

Definition at line 40 of file timer.c.

o2s_timer_start()

o2s_timer_t o2s_timer_start	(	o2s_timer_t	timer,
		unsigned	milliseconds )

Arm timer for the specified duration, in milliseconds.

Returns

another timer object whose member armed is false if unable to start

Definition at line 82 of file timer.c.