touch_loss.c File Reference

Touch events that never arrived, and an arm that must not outlive one. More...

#include "touch_loss.h"
#include <stddef.h>

Macros
#define	HALF_RANGE   0x80000000u

Functions
void	touch_seq_rx_init (touch_seq_rx_t *rx)
	Nothing taken yet: the first event is expected to carry 1.
uint32_t	touch_seq_take (touch_seq_rx_t *rx, uint32_t seq)
	An event numbered seq has been taken off the queue.
uint32_t	touch_seq_tail (touch_seq_rx_t *rx, uint32_t published)
	The queue has been drained.
bool	arm_watch_take_ok (uint32_t loss_gen_stamp, uint32_t loss_gen_now, uint32_t lost_notice_seq, uint32_t consumed_seq)
	May an arm taken now go ahead?
bool	stop_mark_keeps (uint32_t mark, uint32_t cur, bool cur_is_event)
	Whether the mark of a STOP the control task applied stays across a loss the render loop has found.
void	arm_watch_begin (arm_watch_t *w, uint32_t loss_gen_stamp, uint32_t drv_gaps_at_take, uint32_t arm_gen)
	An arm was applied: watch it from here.
bool	arm_watch_lost (arm_watch_t *w, uint32_t loss_gen_now, uint32_t drv_gaps_now, uint32_t acked_arm_gen)
	One look, once the snapshot has been published.
void	arm_watch_end (arm_watch_t *w)
	The bench disarmed for any reason: nothing is left to watch.

Detailed Description

Touch events that never arrived, and an arm that must not outlive one.

See touch_loss.h.

SPDX-License-Identifier: MIT

Function Documentation

arm_watch_begin()

void arm_watch_begin	(	arm_watch_t *	w,
		uint32_t	loss_gen_stamp,
		uint32_t	drv_gaps_at_take,
		uint32_t	arm_gen )

An arm was applied: watch it from here.

Parameters

w	Watch state.
loss_gen_stamp	Render loop loss count at posting.
drv_gaps_at_take	Control task gap count when the arm was taken.
arm_gen	Number of this arm.

arm_watch_end()

void arm_watch_end

(

arm_watch_t *

w

)

The bench disarmed for any reason: nothing is left to watch.

Parameters

w	Watch state.

arm_watch_lost()

bool arm_watch_lost	(	arm_watch_t *	w,
		uint32_t	loss_gen_now,
		uint32_t	drv_gaps_now,
		uint32_t	acked_arm_gen )

One look, once the snapshot has been published.

Returns true when the arm has to be undone: a loss of either kind since it was taken, before the render loop acknowledged arm_gen. A loss is looked for before the acknowledgement, so one that arrives with it still retires the arm. The watch ends either way it resolves.

Parameters

w	Watch state.
loss_gen_now	Render loop loss count now.
drv_gaps_now	Control task gap count now.
acked_arm_gen	Arm number the render loop acknowledged.

Returns

true when the arm has to be undone.

arm_watch_take_ok()

bool arm_watch_take_ok	(	uint32_t	loss_gen_stamp,
		uint32_t	loss_gen_now,
		uint32_t	lost_notice_seq,
		uint32_t	consumed_seq )

May an arm taken now go ahead?

False when the render loop has dropped gestures since it posted the arm (loss_gen_now differs from loss_gen_stamp), or when a loss notice for the render loop was queued after the last event it had consumed when it posted (lost_notice_seq is later than consumed_seq; both 0 means none).

Parameters

loss_gen_stamp	Render loop loss count stamped on the arm.
loss_gen_now	Render loop loss count now.
lost_notice_seq	Sequence of the last loss notice queued; 0 for none.
consumed_seq	Sequence of the last event the render loop consumed; 0 for none.

Returns

true when the arm may go ahead.

stop_mark_keeps()

bool stop_mark_keeps	(	uint32_t	mark,
		uint32_t	cur,
		bool	cur_is_event )

Whether the mark of a STOP the control task applied stays across a loss the render loop has found.

The control task applies a STOP at its press and marks the press with the number it gives it in the render loop's queue, so the router's latch of the same press does not stop the bench a second time. A loss cancels the router's gestures. A press the router has yet to take still latches after that, and needs the mark: one queued after the item that shows the loss, or the event whose arrival showed it, which is dispatched after the cancel. A press numbered before that item was taken already or is among the lost, and the cancel decides it. The numbers wrap.

Parameters

mark	The marked press's number; 0 for none.
cur	The number of the item that showed the loss: the notice or the event after a gap, or the last published number for a loss at the end of a drain.
cur_is_event	Whether that item is an event the router takes next.

Returns

True to keep the mark.

touch_seq_rx_init()

void touch_seq_rx_init

(

touch_seq_rx_t *

rx

)

Nothing taken yet: the first event is expected to carry 1.

Parameters

rx	Consumer state to initialise.

touch_seq_tail()

uint32_t touch_seq_tail	(	touch_seq_rx_t *	rx,
		uint32_t	published )

The queue has been drained.

published is the producer's last published number, read before the drain began: every event up to it had been offered by then, so any of them not taken is lost. Returns how many. Read after the drain instead, it could name an event offered during it and still in the queue.

Parameters

rx	Consumer state.
published	Producer's last published number, read before the drain.

Returns

The number of events offered and not taken.

touch_seq_take()

uint32_t touch_seq_take	(	touch_seq_rx_t *	rx,
		uint32_t	seq )

An event numbered seq has been taken off the queue.

Returns how many events before it never arrived; nonzero means the consumer's record of the glass is stale and has to be dropped before this event is handled.

Parameters

rx	Consumer state.
seq	Number the event carries.

Returns

The number of events that never arrived before this one.