---
name: "rthread"
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"
---

# rthread(3)

Roy threading API

## NAME

rthread - Roy threading API

## SYNOPSIS

\#include \<roy.h\>

RThread \* rthread\_create (RThreadFunction \*function, void \*user\_data);

void rthread\_exit (void \*user\_data);

void rthread\_free (RThread \*thread);

int rthread\_waitfor (RThread \*thread, void \*\*user\_data);

int rthread\_err (RThread \*thread);

char \* rthread\_strerror (RThread \*thread);

void rthread\_yield\_if\_coop ();

## DESCRIPTION

Roy implements a very thin, portable interface to threads that works on  any UNIX system with pthreads or the ability to use PTH, as well as Win32 systems.  The API is fairly small for now but will likely be expanded in future releases as requirements expand.

By default, rthread uses pthreads on UNIX systems, but may also use GNU PTH as a fallback, or as an alternative for pthreads.  See  http://www.gnu.org/software/pth for details on PTH.  pthreads can be disabled at compile time using the --without-pthreads argument to configure.

*rthread\_create*(3) creates a new thread, running *function*.  *user\_data* is passed to *function* as the first argument.  The definition for the function pointer is:

typedef void \* (RThreadFunction) (void \*user\_data);

So a typical declaration for this function might look like:

void \* new\_thread (void \*data);

The return value can be retrieved by another thread by using *rthread\_waitfor*(3).

*rthread\_exit*(3) causes a thread to terminate.  The *user\_data* argument may be set and gathered in another thread by using *rthread\_waitfor*(3).

*rthread\_free*(3) should always be called on the RThread structure returned by *rthread\_create*(3).  This can be done at any time and will not affect the running of the thread, except that this handle may be needed later for various operations.

*rthread\_waitfor*(3) waits for the specified *thread* to exit or return.  The *user\_data* argument will then be set to the value returned or specified in *rthread\_exit*(3).

*rthread\_err*(3) returns non-zero if an error occured in the last operation performed on *thread*.

*rthread\_strerror*(3) should be used to print out any errors that have occured on a thread.  *thread* will contain the error code of the last error.

*rthread\_yield\_if\_coop*(3) will cause a yield of the current threads execution to another thread IF the underlying threading system is cooperative.  This includes PTH and the pthread compatibility library it provides.

## RETURN VALUE

*rthread\_create*(3) returns a valid RThread structure which can be used by *rthread\_waitfor*(3) to gather return information and as a syncronization facility.  In the event of an error, the structure is flagged internally. This condition can be checked using *rthread\_err*(3).

*rthread\_waitfor*(3) returns non-zero if an error occurrs.  This error can be retrieved using *rthread\_strerror*(3) and can also be checked with *rthread\_err*(3).

*rthread\_err*(3) returns non-zero if an error had recently occured in an rthread function call.

*rthread\_strerror*(3) returns a static string containing the text of the error message.

All other functions do not return a value.

## SEE ALSO

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