delay_line.h File Reference

#include <string.h>
#include <stdint.h>
#include "assert.h"
#include "core.h"
#include "crc64.h"
#include "time.h"

Include dependency graph for delay_line.h:

Go to the source code of this file.

Data Structures
struct	delay_line_t

Macros
#define	DEF_DELAY_LINE_PULL(typename, abbrev_type)
#define	DEF_DELAY_LINE_PEEK(typename, abbrev_type)
#define	DEF_DELAY_LINE_PUSH(typename, abbrev_type)
#define	DEF_DELAY_LINE_PUSH_IMM(typename, abbrev_type)
#define	DELAY_LINE_PUSH(line, value)    DELAY_LINE_PUSH_macro_requires_C11_or_greater
#define	DELAY_LINE_PUSH_IMM(line, value)    DELAY_LINE_PUSH_IMM_macro_requires_C11_or_greater

Typedefs
typedef uint64_t(*	delay_line_time_func_t) (void *userinfo)

Functions
static void	delay_line_init (delay_line_t *line, uint64_t delay_us)
static void	delay_line_init_time_func (delay_line_t *line, uint64_t delay_us, delay_line_time_func_t time_func, void *time_func_userinfo)
static void	delay_line_refresh_delay (delay_line_t *line)
static void	delay_line_set_delay (delay_line_t *line, uint64_t delay_us)
static uint64_t	delay_line_get_delay (const delay_line_t *line)
static uint64_t	delay_line_get_delay_act (const delay_line_t *line)
static void	delay_line_set_rand (delay_line_t *line, double rand_fract)
static double	delay_line_get_rand (const delay_line_t *line)
static int64_t	delay_line_pull_i64 (delay_line_t *line)
static uint64_t	delay_line_pull_u64 (delay_line_t *line)
static double	delay_line_pull_f64 (delay_line_t *line)
static int64_t	delay_line_peek_i64 (const delay_line_t *line)
static uint64_t	delay_line_peek_u64 (const delay_line_t *line)
static double	delay_line_peek_f64 (const delay_line_t *line)
static int64_t	delay_line_peek_i64_new (const delay_line_t *line)
static uint64_t	delay_line_peek_u64_new (const delay_line_t *line)
static double	delay_line_peek_f64_new (const delay_line_t *line)
static int64_t	delay_line_push_i64 (delay_line_t *line, int64_t value)
static uint64_t	delay_line_push_u64 (delay_line_t *line, uint64_t value)
static double	delay_line_push_f64 (delay_line_t *line, double value)
static int64_t	delay_line_push_imm_i64 (delay_line_t *line, int64_t value)
static uint64_t	delay_line_push_imm_u64 (delay_line_t *line, uint64_t value)
static double	delay_line_push_imm_f64 (delay_line_t *line, double value)
static uint64_t	delay_line_get_time_since_change (const delay_line_t *line)

Detailed Description

Implements a generic variable that changes after a short delay. You need to initialize the variable using delay_line_init(). Subsequently, you can push changes to it and read the current value. When a change is made, it is propagated into the variable after the delay with which the variable was initialized.

Definition in file delay_line.h.

Macro Definition Documentation

DEF_DELAY_LINE_PEEK

#define DEF_DELAY_LINE_PEEK	(		typename,
			abbrev_type
	)

Value:

static inline typename \
delay_line_peek_ ## abbrev_type(const delay_line_t *line) \
{ \
    ASSERT(line != NULL); \
    return (line->abbrev_type); \
}

Definition at line 244 of file delay_line.h.

DEF_DELAY_LINE_PULL

#define DEF_DELAY_LINE_PULL	(		typename,
			abbrev_type
	)

Value:

static inline typename \
delay_line_pull_ ## abbrev_type(delay_line_t *line) \
{ \
    uint64_t now; \
    ASSERT(line != NULL); \
    now = (line->time_func != NULL ? \
        line->time_func(line->time_func_userinfo) : microclock()); \
    if (line->abbrev_type ## _new != line->abbrev_type && \
        now - line->changed_t >= line->delay_us) { \
        line->abbrev_type = line->abbrev_type ## _new; \
        delay_line_refresh_delay(line); \
    } \
    return (line->abbrev_type); \
}

Definition at line 212 of file delay_line.h.

DEF_DELAY_LINE_PUSH

#define DEF_DELAY_LINE_PUSH	(		typename,
			abbrev_type
	)

Value:

static inline typename \
delay_line_push_ ## abbrev_type(delay_line_t *line, typename value) \
{ \
    uint64_t now; \
    ASSERT(line != NULL); \
    now = (line->time_func != NULL ? \
        line->time_func(line->time_func_userinfo) : microclock()); \
    if (line->abbrev_type == line->abbrev_type ## _new && \
        value != line->abbrev_type ## _new) { \
        line->changed_t = now; \
        delay_line_refresh_delay(line); \
    } \
    line->abbrev_type ## _new = value; \
    return (delay_line_pull_ ## abbrev_type(line)); \
}

Definition at line 282 of file delay_line.h.

DEF_DELAY_LINE_PUSH_IMM

#define DEF_DELAY_LINE_PUSH_IMM	(		typename,
			abbrev_type
	)

Value:

static inline typename \
delay_line_push_imm_ ## abbrev_type(delay_line_t *line, typename value) \
{ \
    ASSERT(line != NULL); \
    line->abbrev_type = value; \
    line->abbrev_type ## _new = value; \
    return (line->abbrev_type); \
}

Definition at line 316 of file delay_line.h.

DELAY_LINE_PUSH

#define DELAY_LINE_PUSH	(		line,
			value
	)		DELAY_LINE_PUSH_macro_requires_C11_or_greater

Generic shorthand for delay_line_push_*. Determines the type of push function to call automatically based on the type of the value passed. Note: this relies on C11 generics and thus requires at least C11 support.

Definition at line 371 of file delay_line.h.

DELAY_LINE_PUSH_IMM

#define DELAY_LINE_PUSH_IMM	(		line,
			value
	)		DELAY_LINE_PUSH_IMM_macro_requires_C11_or_greater

Generic shorthand for delay_line_push_imm_*. Determines the type of push function to call automatically based on the type of the value passed. Note: this relies on C11 generics and thus requires at least C11 support.

Definition at line 373 of file delay_line.h.

Typedef Documentation

delay_line_time_func_t

typedef uint64_t(* delay_line_time_func_t) (void *userinfo)

Callback function that can be passed to delay_line_init_time_func(). This allows you to provide a custom timing function, instead of relaying on the OS's real time clock.

See also

delay_line_init_time_func()

Definition at line 55 of file delay_line.h.

Function Documentation

delay_line_get_delay()

static uint64_t delay_line_get_delay ( const delay_line_t *  line )

static

Returns

The base time delay in microseconds of the delay line. This doesn't include any randomness you may have specified using delay_line_set_rand().

Definition at line 159 of file delay_line.h.

delay_line_get_delay_act()

static uint64_t delay_line_get_delay_act ( const delay_line_t *  line )

static

Returns

The actual time delay in microseconds of the delay line. This includes the randomness of randomized delay lines, configured through delay_line_set_rand(). Subsequent firings of a randomized delay line will return different values here.

Definition at line 172 of file delay_line.h.

delay_line_get_rand()

static double delay_line_get_rand ( const delay_line_t *  line )

static

Returns

The randomness factor of the delay line, as previously set using delay_line_set_rand(). Newly created delay lines will always return 0 here.

Definition at line 207 of file delay_line.h.

delay_line_get_time_since_change()

static uint64_t delay_line_get_time_since_change ( const delay_line_t *  line )

static

Returns

The amount of time elapsed since the delay line has last changed to reflect a new value. This uses the delay line's own timing function (in case one is configured), or the OS's real time clock.

CAUTION: do NOT use this for precise interval timing. Delay lines can be used as simple timed triggers, but they don't keep time accurately, or account for triggering-overshoot. If you try this, your clock will end up slipping and running too slow!

Definition at line 388 of file delay_line.h.

delay_line_init()

static void delay_line_init ( delay_line_t *  line, uint64_t  delay_us  )

static

Initializes a delay line variable.

Parameters

line	Pointer to the delay line to initialize.
delay_us	Microsecond delay between pushing a new value to the delay line before the new value takes effect on read-back.

Definition at line 89 of file delay_line.h.

delay_line_init_time_func()

static void delay_line_init_time_func ( delay_line_t *  line, uint64_t  delay_us, delay_line_time_func_t  time_func, void *  time_func_userinfo  )

static

Same as delay_line_init(), but provides a custom timing function, instead of using the operating system's real time clock. You can use this to implement time delays that respect X-Plane variable simulation rate and thus operate correctly when the sim is running time-accelerated.

Parameters

time_func	A callback that the delay line uses for timing. This must return the current time in microseconds (the starting point doesn't matter, but it must never wrap around).
time_func_userinfo	Optional argument which will be passed to time_func every time it is called.

Definition at line 110 of file delay_line.h.

delay_line_peek_f64()

static double delay_line_peek_f64 ( const delay_line_t *  line )

static

Same as delay_line_peek_i64(), but returns the current value as a double.

Definition at line 265 of file delay_line.h.

delay_line_peek_f64_new()

static double delay_line_peek_f64_new ( const delay_line_t *  line )

static

Same as delay_line_peek_i64_new(), but returns the new value as a double.

Definition at line 280 of file delay_line.h.

delay_line_peek_i64()

static int64_t delay_line_peek_i64 ( const delay_line_t *  line )

static

Accessor function to peek at the current value of a delay line as an int64_t. Unlike delay_line_pull_i64(), this will never cause the value to change. Can be used in combination with delay_line_push_i64 to look for a state change in a delay line in response to the passage of time.

Definition at line 257 of file delay_line.h.

delay_line_peek_i64_new()

static int64_t delay_line_peek_i64_new ( const delay_line_t *  line )

static

Same as delay_line_peek_i64(), but instead of looking at the current value in the delay line, this looks at a new incoming value, without causing the delay line to change.

Definition at line 272 of file delay_line.h.

delay_line_peek_u64()

static uint64_t delay_line_peek_u64 ( const delay_line_t *  line )

static

Same as delay_line_peek_i64(), but returns the current value as a uint64_t.

Definition at line 261 of file delay_line.h.

delay_line_peek_u64_new()

static uint64_t delay_line_peek_u64_new ( const delay_line_t *  line )

static

Same as delay_line_peek_i64_new(), but returns the new value as a uint64_t.

Definition at line 276 of file delay_line.h.

delay_line_pull_f64()

static double delay_line_pull_f64 ( delay_line_t *  line )

static

Same as delay_line_pull_i64(), but returns the current value as a double.

Definition at line 242 of file delay_line.h.

delay_line_pull_i64()

static int64_t delay_line_pull_i64 ( delay_line_t *  line )

static

Accessor function to pull the current value from a delay line as an int64_t. If a new value has been pushed to the delay line, this function keeps returning the old value until the delay line's delay has elapsed, after which it will start returning the new value.

Definition at line 234 of file delay_line.h.

delay_line_pull_u64()

static uint64_t delay_line_pull_u64 ( delay_line_t *  line )

static

Same as delay_line_pull_i64(), but returns the current value as a uint64_t.

Definition at line 238 of file delay_line.h.

delay_line_push_f64()

static double delay_line_push_f64 ( delay_line_t *  line, double  value  )

static

Same as delay_line_push_i64(), but pushes a new double value.

Definition at line 314 of file delay_line.h.

delay_line_push_i64()

static int64_t delay_line_push_i64 ( delay_line_t *  line, int64_t  value  )

static

This function pushes a new int64_t value to a delay line. If the new value is different from the current value of the delay line, the new value will become the delay line's current value after the delay line's time delay has elapsed.

Returns

The current value of the delay line (equivalent to calling delay_line_pull_i64()).

Definition at line 306 of file delay_line.h.

delay_line_push_imm_f64()

static double delay_line_push_imm_f64 ( delay_line_t *  line, double  value  )

static

Same as delay_line_push_imm_i64(), but pushes a new double value.

Definition at line 337 of file delay_line.h.

delay_line_push_imm_i64()

static int64_t delay_line_push_imm_i64 ( delay_line_t *  line, int64_t  value  )

static

Same as delay_line_push_i64(), but doesn't wait for the time delay. The new value immediately becomes the delay line's current value.

Definition at line 329 of file delay_line.h.

delay_line_push_imm_u64()

static uint64_t delay_line_push_imm_u64 ( delay_line_t *  line, uint64_t  value  )

static

Same as delay_line_push_imm_i64(), but pushes a new uint64_t value.

Definition at line 333 of file delay_line.h.

delay_line_push_u64()

static uint64_t delay_line_push_u64 ( delay_line_t *  line, uint64_t  value  )

static

Same as delay_line_push_i64(), but pushes a new uint64_t value.

Definition at line 310 of file delay_line.h.

delay_line_refresh_delay()

static void delay_line_refresh_delay ( delay_line_t *  line )

static

For delay lines which utilize a randomized factor, causes them to recompute the next firing delay. For delay lines without any randomness to their delay, this does nothing.

Definition at line 128 of file delay_line.h.

delay_line_set_delay()

static void delay_line_set_delay ( delay_line_t *  line, uint64_t  delay_us  )

static

Changes the time delay of the delay line.

Definition at line 144 of file delay_line.h.

delay_line_set_rand()

static void delay_line_set_rand ( delay_line_t *  line, double  rand_fract  )

static

Configures randomness for the delay line. Initially, all delay lines are completely fixed-length and deterministic. Sometimes, it is useful to simulate a some variability in the delay of the delay line. The random time delay is recomputed every time the delay line changes state.

Parameters

rand_fract

The fraction of randomness that should be applied to the delay line's delay. This is applied as a fraction of the base time delay, in both directions equally and linearly. So if you pass rand_fract=0.4, that means the delay line will fire randomly between 0.6x and 1.4x its base time delay.

Definition at line 192 of file delay_line.h.