---
name: "rthread_event"
section: "3"
platform: "linux"
package: "libroy-dev"
version: "1.0.8-1"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/rthread_event"
---

# rthread\_event(3)

Roy threading API

## NAME

rthread - Roy threading API

## SYNOPSIS

\#include \<roy.h\>

RThreadEvent rthread\_event\_new (int auto\_reset);

void rthread\_event\_destroy (RThreadEvent event);

void rthread\_event\_wait (RThreadEvent event);

void rthread\_event\_set (RThreadEvent event);

void rthread\_event\_reset (RThreadEvent event);

## DESCRIPTION

These functions add event support to the RThread API.  Events allow threads to syncronize at control points.  It's like a gate that opens to allow one or all threads to continue execution.

This API is tailored after the Win32 API as it was easier to make pthreads behave in the manner the Win32 API behaves than vice versa.

*rthread\_event\_new*(3) initializes an event structure for use. Note the lack of a pointer for this type.  This is intentional as the type is defined differently on different platforms.  You must always declare the mutex without a pointer.  The \\*auto\_reset* argument should be TRUE if you wish the event to automatically reset itself after being set with *rthread\_event\_set*(3), or whether it should remain open, allowing all threads to pass.  If TRUE, only 1 thread will be allowed to pass when the event is set.  If FALSE, you must use *rthread\_event\_reset*(3) to reset the event, stopping more threads from passing.

*rthread\_event\_destroy*(3) This frees up any memory allocated by *rthread\_event\_new*(3) and cleans up the event.  If there are any threads waiting on the event when this is called, the behavior is undefined.

*rthread\_event\_wait*(3) causes the calling thread to block on  *event* until the event is set.  If the event is not an auto resetting event, and is already set, the thread will pass right through.

*rthread\_event\_set*(3) sets *event* allowing 1 or more threads to pass.  If the event is an auto\_reset event, only 1 thread will be allowed to pass.  If no thread is currently waiting on the event, the next thread to reach the event will be allowed to continue.  If the event is NOT an auto\_reset event, then the gate will be open for all threads to pass until  *rthread\_event\_reset*(3) is called.

*rthread\_event\_reset*(3) is only used for events that are NOT auto\_reset.  This resets the event, 'closing the gate' so threads can no longer proceed past the event point.

## RETURN VALUES

Only *rthread\_event\_new*(3) has a return value.  It should never fail.

## SEE ALSO

[*roy*(3)](/roy/3.md), [*rthread*(3)](/rthread/3.md),  [*rthread\_mutex*(3)](/rthread_mutex/3.md)