1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
//-----------------------------------------------------------------------------
// *! (C) Copyright International Business Machines Corp. 2014
// *! All Rights Reserved -- Property of IBM
// *! *** IBM Confidential ***
//-----------------------------------------------------------------------------
/// \file pk_semaphore_init.c
/// \brief PK semaphore API initialization routines
///
/// The entry points in this file are routines that are typically used during
/// initialization, and their code space could be deallocated and recovered if
/// no longer needed by the application after initialization.
#include "pk.h"
/// Create (initialize) a semaphore
///
/// \param semaphore A pointer to an PkSemaphore structure to initialize
///
/// \param initial_count The initial count of the semaphore
///
/// \param max_count The maximum count allowed in the semaphore, for error
/// checking
///
/// Semaphores are created (initialized) by a call of \c
/// pk_semaphore_create(), using an application-provided instance of an \c
/// PkSemaphore structure. This structure \e is the semaphore, so the
/// application must never modify the structure if the semaphore is in use.
/// PK has no way to know if an \c PkSemaphore structure provided to
/// \c pk_semaphore_create() is safe to use as a semaphore, and will silently
/// modify whatever memory is provided.
///
/// PK provides two simple overflow semantics based on the value of max_count
/// in the call of \c pk_semaphore_create().
///
/// If \a max_count = 0, then posting to the semaphore first increments the
/// internal count by 1. Overflows are ignored and will wrap the internal
/// count through 0.
///
/// If \a max_count != 0, then posting to the semaphore first increments the
/// internal count by 1, wrapping through 0 in the event of overflow. If the
/// resulting count is greater than max_count, \c pk_semaphore_post() will
/// return the error \c -PK_SEMAPHORE_POST_OVERFLOW to the caller.
///
/// In most applications it is probably best to use the \a max_count != 0
/// semantics to trap programming errors, unless there is a specific
/// application where overflow is expected and ignorable. As a fine point of
/// the specification, a \a max_count of 0 is equivalent to a max_count of
/// 0xFFFFFFFF.
///
/// Return values other then PK_OK (0) are errors; see \ref pk_errors
///
/// \retval 0 Successful completion
///
/// \retval -PK_INVALID_SEMAPHORE_AT_CREATE The \a semaphore is a null (0)
/// pointer.
///
/// \retval -PK_INVALID_ARGUMENT_SEMAPHORE The \a max_count is non-zero
/// and less than the \a initial_count.
int
pk_semaphore_create(PkSemaphore *semaphore,
PkSemaphoreCount initial_count,
PkSemaphoreCount max_count)
{
if (PK_ERROR_CHECK_API) {
PK_ERROR_IF(semaphore == 0, PK_INVALID_SEMAPHORE_AT_CREATE);
PK_ERROR_IF((max_count != 0) && (initial_count > max_count),
PK_INVALID_ARGUMENT_SEMAPHORE);
}
__pk_thread_queue_clear(&(semaphore->pending_threads));
semaphore->count = initial_count;
semaphore->max_count = max_count;
return PK_OK;
}
|
