Daniel Vilela / Semaphore

Dependents:   I2C

Semaphore.h@0:196198ce7df2, 2019-11-27 (annotated)

Committer:
daniwestside
Date:
Wed Nov 27 11:11:02 2019 +0000
Revision:
0:196198ce7df2
czxczxccc

Who changed what in which revision?

UserRevisionLine numberNew contents of line
daniwestside 0:196198ce7df2 1 /* mbed Microcontroller Library
daniwestside 0:196198ce7df2 2 * Copyright (c) 2006-2012 ARM Limited
daniwestside 0:196198ce7df2 3 *
daniwestside 0:196198ce7df2 4 * Permission is hereby granted, free of charge, to any person obtaining a copy
daniwestside 0:196198ce7df2 5 * of this software and associated documentation files (the "Software"), to deal
daniwestside 0:196198ce7df2 6 * in the Software without restriction, including without limitation the rights
daniwestside 0:196198ce7df2 7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
daniwestside 0:196198ce7df2 8 * copies of the Software, and to permit persons to whom the Software is
daniwestside 0:196198ce7df2 9 * furnished to do so, subject to the following conditions:
daniwestside 0:196198ce7df2 10 *
daniwestside 0:196198ce7df2 11 * The above copyright notice and this permission notice shall be included in
daniwestside 0:196198ce7df2 12 * all copies or substantial portions of the Software.
daniwestside 0:196198ce7df2 13 *
daniwestside 0:196198ce7df2 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
daniwestside 0:196198ce7df2 15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
daniwestside 0:196198ce7df2 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
daniwestside 0:196198ce7df2 17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
daniwestside 0:196198ce7df2 18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
daniwestside 0:196198ce7df2 19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
daniwestside 0:196198ce7df2 20 * SOFTWARE.
daniwestside 0:196198ce7df2 21 */
daniwestside 0:196198ce7df2 22 #ifndef SEMAPHORE_H
daniwestside 0:196198ce7df2 23 #define SEMAPHORE_H
daniwestside 0:196198ce7df2 24
daniwestside 0:196198ce7df2 25 #include <stdint.h>
daniwestside 0:196198ce7df2 26 #include "mbed_rtos_types.h"
daniwestside 0:196198ce7df2 27 #include "mbed_rtos1_types.h"
daniwestside 0:196198ce7df2 28 #include "mbed_rtos_storage.h"
daniwestside 0:196198ce7df2 29 #include "platform/mbed_toolchain.h"
daniwestside 0:196198ce7df2 30 #include "platform/NonCopyable.h"
daniwestside 0:196198ce7df2 31
daniwestside 0:196198ce7df2 32 namespace rtos {
daniwestside 0:196198ce7df2 33 /** \addtogroup rtos */
daniwestside 0:196198ce7df2 34 /** @{*/
daniwestside 0:196198ce7df2 35 /**
daniwestside 0:196198ce7df2 36 * \defgroup rtos_Semaphore Semaphore class
daniwestside 0:196198ce7df2 37 * @{
daniwestside 0:196198ce7df2 38 */
daniwestside 0:196198ce7df2 39
daniwestside 0:196198ce7df2 40 /** The Semaphore class is used to manage and protect access to a set of shared resources.
daniwestside 0:196198ce7df2 41 *
daniwestside 0:196198ce7df2 42 * @note
daniwestside 0:196198ce7df2 43 * Memory considerations: The semaphore control structures will be created on current thread's stack, both for the mbed OS
daniwestside 0:196198ce7df2 44 * and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
daniwestside 0:196198ce7df2 45 */
daniwestside 0:196198ce7df2 46 class Semaphore : private mbed::NonCopyable<Semaphore> {
daniwestside 0:196198ce7df2 47 public:
daniwestside 0:196198ce7df2 48 /** Create and Initialize a Semaphore object used for managing resources.
daniwestside 0:196198ce7df2 49 @param count number of available resources; maximum index value is (count-1). (default: 0).
daniwestside 0:196198ce7df2 50
daniwestside 0:196198ce7df2 51 @note You cannot call this function from ISR context.
daniwestside 0:196198ce7df2 52 */
daniwestside 0:196198ce7df2 53 Semaphore(int32_t count = 0);
daniwestside 0:196198ce7df2 54
daniwestside 0:196198ce7df2 55 /** Create and Initialize a Semaphore object used for managing resources.
daniwestside 0:196198ce7df2 56 @param count number of available resources
daniwestside 0:196198ce7df2 57 @param max_count maximum number of available resources
daniwestside 0:196198ce7df2 58
daniwestside 0:196198ce7df2 59 @note You cannot call this function from ISR context.
daniwestside 0:196198ce7df2 60 */
daniwestside 0:196198ce7df2 61 Semaphore(int32_t count, uint16_t max_count);
daniwestside 0:196198ce7df2 62
daniwestside 0:196198ce7df2 63 /** Wait until a Semaphore resource becomes available.
daniwestside 0:196198ce7df2 64
daniwestside 0:196198ce7df2 65 @deprecated Do not use this function. This function has been replaced with acquire(), try_acquire() and try_acquire_for() functions.
daniwestside 0:196198ce7df2 66
daniwestside 0:196198ce7df2 67 @param millisec timeout value. (default: osWaitForever).
daniwestside 0:196198ce7df2 68 @return number of available tokens, before taking one; or -1 in case of incorrect parameters
daniwestside 0:196198ce7df2 69
daniwestside 0:196198ce7df2 70 @note You may call this function from ISR context if the millisec parameter is set to 0.
daniwestside 0:196198ce7df2 71 */
daniwestside 0:196198ce7df2 72 MBED_DEPRECATED_SINCE("mbed-os-5.13", "Replaced with acquire, try_acquire() and try_acquire_for() functions")
daniwestside 0:196198ce7df2 73 int32_t wait(uint32_t millisec = osWaitForever);
daniwestside 0:196198ce7df2 74
daniwestside 0:196198ce7df2 75 /** Wait until a Semaphore resource becomes available.
daniwestside 0:196198ce7df2 76
daniwestside 0:196198ce7df2 77 @deprecated Do not use this function. This function has been replaced with try_acquire_until().
daniwestside 0:196198ce7df2 78
daniwestside 0:196198ce7df2 79 @param millisec absolute timeout time, referenced to Kernel::get_ms_count()
daniwestside 0:196198ce7df2 80 @return number of available tokens, before taking one; or -1 in case of incorrect parameters
daniwestside 0:196198ce7df2 81 @note the underlying RTOS may have a limit to the maximum wait time
daniwestside 0:196198ce7df2 82 due to internal 32-bit computations, but this is guaranteed to work if the
daniwestside 0:196198ce7df2 83 wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
daniwestside 0:196198ce7df2 84 the acquire attempt will time out earlier than specified.
daniwestside 0:196198ce7df2 85
daniwestside 0:196198ce7df2 86 @note You cannot call this function from ISR context.
daniwestside 0:196198ce7df2 87 */
daniwestside 0:196198ce7df2 88 MBED_DEPRECATED_SINCE("mbed-os-5.13", "Replaced with try_acquire_until()")
daniwestside 0:196198ce7df2 89 int32_t wait_until(uint64_t millisec);
daniwestside 0:196198ce7df2 90
daniwestside 0:196198ce7df2 91 /** Wait until a Semaphore resource becomes available.
daniwestside 0:196198ce7df2 92
daniwestside 0:196198ce7df2 93 @note You cannot call this function from ISR context.
daniwestside 0:196198ce7df2 94 */
daniwestside 0:196198ce7df2 95 void acquire();
daniwestside 0:196198ce7df2 96
daniwestside 0:196198ce7df2 97 /** Try to acquire a Semaphore resource, and return immediately
daniwestside 0:196198ce7df2 98 @return true if a resource was acquired, false otherwise.
daniwestside 0:196198ce7df2 99 @note equivalent to try_acquire_for(0)
daniwestside 0:196198ce7df2 100
daniwestside 0:196198ce7df2 101 @note You may call this function from ISR context.
daniwestside 0:196198ce7df2 102 */
daniwestside 0:196198ce7df2 103 bool try_acquire();
daniwestside 0:196198ce7df2 104
daniwestside 0:196198ce7df2 105 /** Wait until a Semaphore resource becomes available.
daniwestside 0:196198ce7df2 106 @param millisec timeout value.
daniwestside 0:196198ce7df2 107 @return true if a resource was acquired, false otherwise.
daniwestside 0:196198ce7df2 108
daniwestside 0:196198ce7df2 109 @note You may call this function from ISR context if the millisec parameter is set to 0.
daniwestside 0:196198ce7df2 110 */
daniwestside 0:196198ce7df2 111 bool try_acquire_for(uint32_t millisec);
daniwestside 0:196198ce7df2 112
daniwestside 0:196198ce7df2 113 /** Wait until a Semaphore resource becomes available.
daniwestside 0:196198ce7df2 114 @param millisec absolute timeout time, referenced to Kernel::get_ms_count()
daniwestside 0:196198ce7df2 115 @return true if a resource was acquired, false otherwise.
daniwestside 0:196198ce7df2 116 @note the underlying RTOS may have a limit to the maximum wait time
daniwestside 0:196198ce7df2 117 due to internal 32-bit computations, but this is guaranteed to work if the
daniwestside 0:196198ce7df2 118 wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
daniwestside 0:196198ce7df2 119 the acquire attempt will time out earlier than specified.
daniwestside 0:196198ce7df2 120
daniwestside 0:196198ce7df2 121 @note You cannot call this function from ISR context.
daniwestside 0:196198ce7df2 122 */
daniwestside 0:196198ce7df2 123 bool try_acquire_until(uint64_t millisec);
daniwestside 0:196198ce7df2 124
daniwestside 0:196198ce7df2 125 /** Release a Semaphore resource that was obtain with Semaphore::acquire.
daniwestside 0:196198ce7df2 126 @return status code that indicates the execution status of the function:
daniwestside 0:196198ce7df2 127 @a osOK the token has been correctly released.
daniwestside 0:196198ce7df2 128 @a osErrorResource the maximum token count has been reached.
daniwestside 0:196198ce7df2 129 @a osErrorParameter internal error.
daniwestside 0:196198ce7df2 130
daniwestside 0:196198ce7df2 131 @note You may call this function from ISR context.
daniwestside 0:196198ce7df2 132 */
daniwestside 0:196198ce7df2 133 osStatus release(void);
daniwestside 0:196198ce7df2 134
daniwestside 0:196198ce7df2 135 /** Semaphore destructor
daniwestside 0:196198ce7df2 136 *
daniwestside 0:196198ce7df2 137 * @note You cannot call this function from ISR context.
daniwestside 0:196198ce7df2 138 */
daniwestside 0:196198ce7df2 139 ~Semaphore();
daniwestside 0:196198ce7df2 140
daniwestside 0:196198ce7df2 141 private:
daniwestside 0:196198ce7df2 142 void constructor(int32_t count, uint16_t max_count);
daniwestside 0:196198ce7df2 143
daniwestside 0:196198ce7df2 144 #if MBED_CONF_RTOS_PRESENT
daniwestside 0:196198ce7df2 145 int32_t _wait(uint32_t millisec);
daniwestside 0:196198ce7df2 146
daniwestside 0:196198ce7df2 147 osSemaphoreId_t _id;
daniwestside 0:196198ce7df2 148 mbed_rtos_storage_semaphore_t _obj_mem;
daniwestside 0:196198ce7df2 149 #else
daniwestside 0:196198ce7df2 150 static bool semaphore_available(void *);
daniwestside 0:196198ce7df2 151 int32_t _count;
daniwestside 0:196198ce7df2 152 uint16_t _max_count;
daniwestside 0:196198ce7df2 153 #endif
daniwestside 0:196198ce7df2 154 };
daniwestside 0:196198ce7df2 155 /** @}*/
daniwestside 0:196198ce7df2 156 /** @}*/
daniwestside 0:196198ce7df2 157 }
daniwestside 0:196198ce7df2 158 #endif
daniwestside 0:196198ce7df2 159
daniwestside 0:196198ce7df2 160