SyncTypeCreate(), SyncTypeCreate_r()

Create a synchronization object

Synopsis:

#include <sys/neutrino.h>

int SyncTypeCreate( 
        unsigned type,
        sync_t * sync,
        const struct _sync_attr_t * attr );

int SyncTypeCreate_r( 
        unsigned type,
        sync_t * sync,
        const struct _sync_attr_t * attr );

Library:

libc

Description:

The SyncTypeCreate() and SyncTypeCreate_r() functions are identical except in the way they indicate errors. See the Returns section for details.

These kernel calls create a synchronization object in the kernel and initializes sync for use in other synchronization kernel calls. The synchronization object is local to the process.

Synchronization objects can be used for mutexes, semaphores, or condition variables.

Don't call SyncTypeCreate() directly; instead, use the POSIX synchronization objects (see pthread_cond_init(), pthread_mutex_init(), pthread_rwlock_init(), and sem_init()).

The type parameter may be one of the following:

_NTO_SYNC_MUTEX_FREE: Create a mutex
_NTO_SYNC_SEM: Create a semaphore
_NTO_SYNC_COND: Create a condition variable

The sync argument contains at least the following members:

Member	Description
`int` count	Count for recursive mutexes and semaphores. Set by the kernel when created.
`int` owner	When a mutex is created, holds the thread ID of the thread that acquired the mutex. When unowned, the value is 0. Set to zero when created.

The current state of sync is summarized below:

Counter	Owner	Description
--	-2	Destroyed mutex
0	-1	Statically initialized; auto-created when used
0	0	Unlocked mutex
count	>0	Recursive counter number of the mutex
count	<-1	If the high bit of count is set, it's a flag meaning "others waiting"
--	-256	Mutex is dead, waits for revival

The attr argument contains at least the following members:

Member	Description
`int` protocol	One of PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT.

If attr is NULL, the default attributes (PTHREAD_PRIO_INHERIT) are assumed.

The synchronization object is destroyed by a call to SyncDestroy().

Blocking states

These calls don't block.

Returns:

The only difference between these functions is the way they indicate errors:

SyncTypeCreate(): If an error occurs, -1 is returned and errno is set. Any other value returned indicates success.
SyncTypeCreate_r(): EOK is returned on success. This function does NOT set errno. If an error occurs, any value in the Errors section may be returned.

Errors:

EAGAIN

All kernel synchronization objects are in use.

EFAULT

A fault occurred when the kernel tried to access sync or attr.

EINVAL

Either

the type isn't one of _NTO_SYNC_COND, _NTO_SYNC_MUTEX_FREE or _NTO_SYNC_SEM
Or:
if the type is correct, and the synchronization object is:
- a mutex -- the protocol isn't one of PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT.
- a mutex and PTHREAD_PRIO_PROTECT is specified -- the ceiling priority isn't within the kernel priority range.
- a condvar -- the clock type is invalid.
- a semaphore -- the semaphore value exceeds SEM_VALUE_MAX.

Classification:

QNX 6

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes