diff options
| author | gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4> | 2013-01-02 13:30:07 +0000 |
|---|---|---|
| committer | gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4> | 2013-01-02 13:30:07 +0000 |
| commit | c66db01792f60dfc8af534e2d7fbcb326efb4873 (patch) | |
| tree | f23b183a1d2b72079c82123c4cb648d5596cb684 /os/various/cpp_wrappers/ch.hpp | |
| parent | 8fa18b0b6b3f5640a2db179ec938f8962f65244c (diff) | |
| download | ChibiOS-c66db01792f60dfc8af534e2d7fbcb326efb4873.tar.gz ChibiOS-c66db01792f60dfc8af534e2d7fbcb326efb4873.tar.bz2 ChibiOS-c66db01792f60dfc8af534e2d7fbcb326efb4873.zip | |
Semaphores wrapper improved and completed.
git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@5016 35acf78f-673a-0410-8e92-d51de3d6d3f4
Diffstat (limited to 'os/various/cpp_wrappers/ch.hpp')
| -rw-r--r-- | os/various/cpp_wrappers/ch.hpp | 129 |
1 files changed, 114 insertions, 15 deletions
diff --git a/os/various/cpp_wrappers/ch.hpp b/os/various/cpp_wrappers/ch.hpp index 6d0eb66c7..efcb49dba 100644 --- a/os/various/cpp_wrappers/ch.hpp +++ b/os/various/cpp_wrappers/ch.hpp @@ -601,47 +601,146 @@ namespace chibios_rt { Semaphore(cnt_t n);
/**
- * @brief Resets a semaphore.
+ * @brief Performs a reset operation on the semaphore.
+ * @post After invoking this function all the threads waiting on the
+ * semaphore, if any, are released and the semaphore counter is set
+ * to the specified, non negative, value.
+ * @note The released threads can recognize they were waked up by a reset
+ * rather than a signal because the @p chSemWait() will return
+ * @p RDY_RESET instead of @p RDY_OK.
*
- * @param[in] n the new semaphore counter value, must be
- * greater or equal to zero
+ * @param[in] n the new value of the semaphore counter. The value must
+ * be non-negative.
*
* @api
*/
void reset(cnt_t n);
/**
- * @brief Wait operation on the semaphore.
+ * @brief Performs a reset operation on the semaphore.
+ * @post After invoking this function all the threads waiting on the
+ * semaphore, if any, are released and the semaphore counter is set
+ * to the specified, non negative, value.
+ * @post This function does not reschedule so a call to a rescheduling
+ * function must be performed before unlocking the kernel. Note that
+ * interrupt handlers always reschedule on exit so an explicit
+ * reschedule must not be performed in ISRs.
+ * @note The released threads can recognize they were waked up by a reset
+ * rather than a signal because the @p chSemWait() will return
+ * @p RDY_RESET instead of @p RDY_OK.
*
- * @retval RDY_OK if the semaphore was signaled or not taken.
- * @retval RDY_RESET if the semaphore was reset.
+ * @param[in] n the new value of the semaphore counter. The value must
+ * be non-negative.
+ *
+ * @iclass
+ */
+ void resetI(cnt_t n);
+
+ /**
+ * @brief Performs a wait operation on a semaphore.
+ *
+ * @return A message specifying how the invoking thread has been
+ * released from the semaphore.
+ * @retval RDY_OK if the thread has not stopped on the semaphore or the
+ * semaphore has been signaled.
+ * @retval RDY_RESET if the semaphore has been reset using @p chSemReset().
*
* @api
*/
msg_t wait(void);
/**
- * @brief Wait operation on the semaphore with timeout.
+ * @brief Performs a wait operation on a semaphore.
*
- * @param[in] time the number of ticks before the operation fails
- * @retval RDY_OK if the semaphore was signaled or not taken.
- * @retval RDY_RESET if the semaphore was reset.
- * @retval RDY_TIMEOUT if the semaphore was not signaled or reset
- * within the specified timeout.
+ * @return A message specifying how the invoking thread has been
+ * released from the semaphore.
+ * @retval RDY_OK if the thread has not stopped on the semaphore or the
+ * semaphore has been signaled.
+ * @retval RDY_RESET if the semaphore has been reset using @p chSemReset().
+ *
+ * @sclass
+ */
+ msg_t waitS(void);
+
+ /**
+ * @brief Performs a wait operation on a semaphore with timeout specification.
+ *
+ * @param[in] time the number of ticks before the operation timeouts,
+ * the following special values are allowed:
+ * - @a TIME_IMMEDIATE immediate timeout.
+ * - @a TIME_INFINITE no timeout.
+ * .
+ * @return A message specifying how the invoking thread has been
+ * released from the semaphore.
+ * @retval RDY_OK if the thread has not stopped on the semaphore or the
+ * semaphore has been signaled.
+ * @retval RDY_RESET if the semaphore has been reset using @p chSemReset().
+ * @retval RDY_TIMEOUT if the semaphore has not been signaled or reset within
+ * the specified timeout.
*
* @api
*/
msg_t waitTimeout(systime_t time);
/**
- * @brief Signal operation on the semaphore.
- * @details The semaphore is signaled, the next thread in queue, if any,
- * is awakened.
+ * @brief Performs a wait operation on a semaphore with timeout specification.
+ *
+ * @param[in] time the number of ticks before the operation timeouts,
+ * the following special values are allowed:
+ * - @a TIME_IMMEDIATE immediate timeout.
+ * - @a TIME_INFINITE no timeout.
+ * .
+ * @return A message specifying how the invoking thread has been
+ * released from the semaphore.
+ * @retval RDY_OK if the thread has not stopped on the semaphore or the
+ * semaphore has been signaled.
+ * @retval RDY_RESET if the semaphore has been reset using @p chSemReset().
+ * @retval RDY_TIMEOUT if the semaphore has not been signaled or reset within
+ * the specified timeout.
+ *
+ * @sclass
+ */
+ msg_t waitTimeoutS(systime_t time);
+
+ /**
+ * @brief Performs a signal operation on a semaphore.
*
* @api
*/
void signal(void);
+ /**
+ * @brief Performs a signal operation on a semaphore.
+ * @post This function does not reschedule so a call to a rescheduling
+ * function must be performed before unlocking the kernel. Note that
+ * interrupt handlers always reschedule on exit so an explicit
+ * reschedule must not be performed in ISRs.
+ *
+ * @iclass
+ */
+ void signalI(void);
+
+ /**
+ * @brief Adds the specified value to the semaphore counter.
+ * @post This function does not reschedule so a call to a rescheduling
+ * function must be performed before unlocking the kernel. Note that
+ * interrupt handlers always reschedule on exit so an explicit
+ * reschedule must not be performed in ISRs.
+ *
+ * @param[in] n value to be added to the semaphore counter. The value
+ * must be positive.
+ *
+ * @iclass
+ */
+ void addCounterI(cnt_t n);
+
+ /**
+ * @brief Returns the semaphore counter value.
+ *
+ * @iclass
+ */
+ cnt_t getCounterI(void);
+
#if CH_USE_SEMSW || defined(__DOXYGEN__)
/**
* @brief Atomic signal and wait operations.
|