Create a synchronization object
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:
- _NTO_SYNC_MUTEX_FREE — create a mutex.
- _NTO_SYNC_SEM — create a semaphore.
- _NTO_SYNC_COND — create a condition variable.
- sync
- A pointer to a sync_t that the kernel sets up for the
synchronization object; see below.
- attr
- A pointer to a _sync_attr structure that specifies
attributes for the object.
This structure contains at least the following members:
- int protocol —
PTHREAD_PRIO_INHERIT or
PTHREAD_PRIO_PROTECT.
Note:
If you use
PTHREAD_PRIO_PROTECT and you want to
change the priority ceiling to a value above the maximum permitted for unprivileged processes,
your process must have the
PROCMGR_AID_PRIORITY ability enabled.
For more information, see
procmgr_ability().
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.
The synchronization object is local to the process.
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.
The sync_t argument contains at least the following members:
- int __count
- The count for recursive mutexes and semaphores.
The kernel sets this member when it creates the synchronization object.
- int __owner
- When a mutex is created, this member holds the thread ID of the thread
that acquired the mutex.
When unowned, the value is 0.
It's set to zero when the synchronization object is 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 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, 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.
- 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 Neutrino
Safety: |
|
Cancellation point |
No |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |