SyncTypeCreate(), SyncTypeCreate_r()

Create a synchronization object


Note: Don't use the SyncTypeCreate() or SyncTypeCreate_r() kernel call directly; instead, use the POSIX functions for synchronization objects (see pthread_cond_init(), pthread_mutex_init(), pthread_rwlock_init(), and sem_init()).

Synopsis:

#include <sys/neutrino.h>

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

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

Arguments:

type
One of the following:
sync
A pointer to a sync_t object that the kernel sets up for the synchronization object; you should treat this as an opaque structure.

Note: It's always safe, and typically faster, to assure that sync is 32-bit aligned.

attr
A pointer to a _sync_attr structure that specifies attributes for the object. This structure contains at least the following members:

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

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The SyncTypeCreate() and SyncTypeCreate_r() kernel calls create a synchronization object in the kernel and initializes sync for use in other synchronization kernel calls. These functions are similar, except for the way they indicate errors. See the Returns section for details.


Caution: You should allocate synchronization objects only in normal memory mappings. On certain processors (e.g. some PPC ones), atomic operations such as calls to pthread_mutex_lock() will cause a fault if the control structure is allocated in uncached memory.

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

You can destroy the synchronization object by calling 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, the function returns -1 and sets errno. Any other value returned indicates success.
SyncTypeCreate_r()
Returns EOK on success. This function does NOT set errno. If an error occurs, the function can return any value in the Errors section.

Errors:

EAGAIN
All kernel synchronization objects are in use.
EBUSY
The synchronization object indicated by sync was previously initialized but hasn't been destroyed.
EFAULT
A fault occurred when the kernel tried to access sync or attr.
EINVAL
Either

Classification:

QNX Neutrino

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

See also:

pthread_cond_init(), pthread_mutex_init(), pthread_rwlock_init(), sem_init(), SyncCondvarSignal(), SyncCondvarWait(), SyncDestroy(), SyncMutexLock(), SyncMutexUnlock()

Synchronization services in the QNX Neutrino Microkernel chapter of the System Architecture guide