mirror of https://github.com/ARMmbed/mbed-os.git
291 lines
13 KiB
C++
291 lines
13 KiB
C++
/* mbed Microcontroller Library
|
|
* Copyright (c) 2006-2019 ARM Limited
|
|
* SPDX-License-Identifier: MIT
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
* of this software and associated documentation files (the "Software"), to deal
|
|
* in the Software without restriction, including without limitation the rights
|
|
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
* copies of the Software, and to permit persons to whom the Software is
|
|
* furnished to do so, subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be included in
|
|
* all copies or substantial portions of the Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
* SOFTWARE.
|
|
*/
|
|
#ifndef THIS_THREAD_H
|
|
#define THIS_THREAD_H
|
|
|
|
#include <stdint.h>
|
|
#include "platform/mbed_toolchain.h"
|
|
#include "rtos/Kernel.h"
|
|
#include "rtos/mbed_rtos_types.h"
|
|
|
|
namespace rtos {
|
|
/** \addtogroup rtos-public-api */
|
|
/** @{*/
|
|
|
|
/**
|
|
* \defgroup rtos_ThisThread ThisThread namespace
|
|
* @{
|
|
*/
|
|
|
|
/** The ThisThread namespace allows controlling the current thread.
|
|
*
|
|
* Example:
|
|
* @code
|
|
* #include "mbed.h"
|
|
* #include "rtos.h"
|
|
*
|
|
* Thread thread;
|
|
* DigitalOut led1(LED1);
|
|
*
|
|
* #define STOP_FLAG 1
|
|
*
|
|
* // Blink function toggles the led in a long running loop
|
|
* void blink(DigitalOut *led) {
|
|
* while (!ThisThread::flags_wait_any_for(STOP_FLAG, 1000)) {
|
|
* *led = !*led;
|
|
* }
|
|
* }
|
|
*
|
|
* // Spawns a thread to run blink for 5 seconds
|
|
* int main() {
|
|
* thread.start(callback(blink, &led1));
|
|
* ThisThread::sleep_for(5000);
|
|
* thread.signal_set(STOP_FLAG);
|
|
* thread.join();
|
|
* }
|
|
* @endcode
|
|
*
|
|
*/
|
|
namespace ThisThread {
|
|
/** Clears the specified Thread Flags of the currently running thread.
|
|
@param flags specifies the flags of the thread that should be cleared.
|
|
@return thread flags before clearing.
|
|
@note You cannot call this function from ISR context.
|
|
@see Thread::flags_set
|
|
*/
|
|
uint32_t flags_clear(uint32_t flags);
|
|
|
|
/** Returns the Thread Flags currently set for the currently running thread.
|
|
@return current thread flags or 0 if not in a valid thread.
|
|
@note You cannot call this function from ISR context.
|
|
@see Thread::flags_set
|
|
*/
|
|
uint32_t flags_get();
|
|
|
|
/** Wait for all of the specified Thread Flags to become signaled for the current thread.
|
|
@param flags specifies the flags to wait for
|
|
@param clear whether to clear the specified flags after waiting for them. (default: true)
|
|
@return actual thread flags before clearing, which will satisfy the wait
|
|
@note You cannot call this function from ISR context.
|
|
@see Thread::flags_set
|
|
*/
|
|
uint32_t flags_wait_all(uint32_t flags, bool clear = true);
|
|
|
|
/** Wait for any of the specified Thread Flags to become signaled for the current thread.
|
|
@param flags specifies the flags to wait for
|
|
@param clear whether to clear the specified flags after waiting for them. (default: true)
|
|
@return actual thread flags before clearing, which will satisfy the wait
|
|
@note You cannot call this function from ISR context.
|
|
@see Thread::flags_set
|
|
*/
|
|
uint32_t flags_wait_any(uint32_t flags, bool clear = true);
|
|
|
|
/** Wait for all of the specified Thread Flags to become signaled for the current thread.
|
|
@param flags specifies the flags to wait for
|
|
@param millisec timeout value.
|
|
@param clear whether to clear the specified flags after waiting for them. (default: true)
|
|
@return actual thread flags before clearing, which may not satisfy the wait
|
|
@note You cannot call this function from ISR context.
|
|
@see Thread::flags_set
|
|
@deprecated Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.
|
|
*/
|
|
MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.")
|
|
uint32_t flags_wait_all_for(uint32_t flags, uint32_t millisec, bool clear = true);
|
|
|
|
/** Wait for all of the specified Thread Flags to become signaled for the current thread.
|
|
@param flags specifies the flags to wait for
|
|
@param rel_time timeout value.
|
|
@param clear whether to clear the specified flags after waiting for them. (default: true)
|
|
@return actual thread flags before clearing, which may not satisfy the wait
|
|
@note You cannot call this function from ISR context.
|
|
@see Thread::flags_set
|
|
*/
|
|
uint32_t flags_wait_all_for(uint32_t flags, Kernel::Clock::duration_u32 rel_time, bool clear = true);
|
|
|
|
/** Wait for all of the specified Thread Flags to become signaled for the current thread.
|
|
@param flags specifies the flags to wait for
|
|
@param millisec absolute timeout time, referenced to Kernel::get_ms_count()
|
|
@param clear whether to clear the specified flags after waiting for them. (default: true)
|
|
@return actual thread flags before clearing, which may not satisfy the wait
|
|
@note You cannot call this function from ISR context.
|
|
@note the underlying RTOS may have a limit to the maximum wait time
|
|
due to internal 32-bit computations, but this is guaranteed to work if the
|
|
wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
|
|
the wait will time out earlier than specified.
|
|
@see Thread::flags_set
|
|
@deprecated Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s`
|
|
rather than `Kernel::get_ms_count() + 5000`.
|
|
*/
|
|
MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s` rather than `Kernel::get_ms_count() + 5000`.")
|
|
uint32_t flags_wait_all_until(uint32_t flags, uint64_t millisec, bool clear = true);
|
|
|
|
/** Wait for all of the specified Thread Flags to become signaled for the current thread.
|
|
@param flags specifies the flags to wait for
|
|
@param abs_time absolute timeout time, referenced to Kernel::Clock
|
|
@param clear whether to clear the specified flags after waiting for them. (default: true)
|
|
@return actual thread flags before clearing, which may not satisfy the wait
|
|
@note You cannot call this function from ISR context.
|
|
@note the underlying RTOS may have a limit to the maximum wait time
|
|
due to internal 32-bit computations, but this is guaranteed to work if the
|
|
wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
|
|
the wait will time out earlier than specified.
|
|
@see Thread::flags_set
|
|
*/
|
|
uint32_t flags_wait_all_until(uint32_t flags, Kernel::Clock::time_point abs_time, bool clear = true);
|
|
|
|
/** Wait for any of the specified Thread Flags to become signaled for the current thread.
|
|
@param flags specifies the flags to wait for
|
|
@param millisec timeout value.
|
|
@param clear whether to clear the specified flags after waiting for them. (default: true)
|
|
@return actual thread flags before clearing, which may not satisfy the wait
|
|
@note You cannot call this function from ISR context.
|
|
@see Thread::flags_set
|
|
@deprecated Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.
|
|
*/
|
|
MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.")
|
|
uint32_t flags_wait_any_for(uint32_t flags, uint32_t millisec, bool clear = true);
|
|
|
|
/** Wait for any of the specified Thread Flags to become signaled for the current thread.
|
|
@param flags specifies the flags to wait for
|
|
@param rel_time timeout value.
|
|
@param clear whether to clear the specified flags after waiting for them. (default: true)
|
|
@return actual thread flags before clearing, which may not satisfy the wait
|
|
@note You cannot call this function from ISR context.
|
|
@see Thread::flags_set
|
|
*/
|
|
uint32_t flags_wait_any_for(uint32_t flags, Kernel::Clock::duration_u32 rel_time, bool clear = true);
|
|
|
|
/** Wait for any of the specified Thread Flags to become signaled for the current thread.
|
|
@param flags specifies the flags to wait for
|
|
@param millisec absolute timeout time, referenced to Kernel::get_ms_count()
|
|
@param clear whether to clear the specified flags after waiting for them. (default: true)
|
|
@return actual thread flags before clearing, which may not satisfy the wait
|
|
@note You cannot call this function from ISR context.
|
|
@note the underlying RTOS may have a limit to the maximum wait time
|
|
due to internal 32-bit computations, but this is guaranteed to work if the
|
|
wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
|
|
the wait will time out earlier than specified.
|
|
@see Thread::flags_set
|
|
@deprecated Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s`
|
|
rather than `Kernel::get_ms_count() + 5000`.
|
|
*/
|
|
MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s` rather than `Kernel::get_ms_count() + 5000`.")
|
|
uint32_t flags_wait_any_until(uint32_t flags, uint64_t millisec, bool clear = true);
|
|
|
|
/** Wait for any of the specified Thread Flags to become signaled for the current thread.
|
|
@param flags specifies the flags to wait for
|
|
@param abs_time absolute timeout time, referenced to Kernel::Clock
|
|
@param clear whether to clear the specified flags after waiting for them. (default: true)
|
|
@return actual thread flags before clearing, which may not satisfy the wait
|
|
@note You cannot call this function from ISR context.
|
|
@note the underlying RTOS may have a limit to the maximum wait time
|
|
due to internal 32-bit computations, but this is guaranteed to work if the
|
|
wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
|
|
the wait will time out earlier than specified.
|
|
@see Thread::flags_set
|
|
*/
|
|
uint32_t flags_wait_any_until(uint32_t flags, Kernel::Clock::time_point abs_time, bool clear = true);
|
|
|
|
/** Sleep for a specified time period in millisec:
|
|
@param millisec time delay value
|
|
@note You cannot call this function from ISR context.
|
|
@note The equivalent functionality is accessible in C via thread_sleep_for.
|
|
@deprecated Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.
|
|
*/
|
|
MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.")
|
|
void sleep_for(uint32_t millisec);
|
|
|
|
/** Sleep for a specified time period:
|
|
@param rel_time time delay value
|
|
@note You cannot call this function from ISR context.
|
|
@note The equivalent functionality is accessible in C via thread_sleep_for.
|
|
*/
|
|
void sleep_for(Kernel::Clock::duration_u32 rel_time);
|
|
|
|
|
|
/** Sleep until a specified time in millisec
|
|
The specified time is according to Kernel::get_ms_count().
|
|
@param millisec absolute time in millisec
|
|
@note You cannot call this function from ISR context.
|
|
@note if millisec is equal to or lower than the current tick count, this
|
|
returns immediately.
|
|
@note The equivalent functionality is accessible in C via thread_sleep_until.
|
|
@deprecated Pass a chrono time_point, not an integer millisecond count. For example use
|
|
`Kernel::Clock::now() + 5s` rather than `Kernel::get_ms_count() + 5000`.
|
|
*/
|
|
MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s` rather than `Kernel::get_ms_count() + 5000`.")
|
|
void sleep_until(uint64_t millisec);
|
|
|
|
/** Sleep until a specified time in millisec
|
|
The specified time is according to Kernel::Clock.
|
|
@param abs_time absolute time
|
|
@note You cannot call this function from ISR context.
|
|
@note if abs_time is equal to or lower than Kernel::Clock::now(), this
|
|
returns immediately.
|
|
@note The equivalent functionality is accessible in C via thread_sleep_until.
|
|
*/
|
|
void sleep_until(Kernel::Clock::time_point abs_time);
|
|
|
|
/** Pass control to next equal-priority thread that is in state READY.
|
|
(Higher-priority READY threads would prevent us from running; this
|
|
will not enable lower-priority threads to run, as we remain READY).
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
void yield();
|
|
|
|
/** Get the thread id of the current running thread.
|
|
@return thread ID for reference by other functions or nullptr in case of error or in ISR context.
|
|
@note You may call this function from ISR context.
|
|
*/
|
|
osThreadId_t get_id();
|
|
|
|
/** Get the thread name of the current running thread.
|
|
@return thread name pointer or nullptr if thread has no name or in case of error.
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
const char *get_name();
|
|
|
|
};
|
|
/** @}*/
|
|
/** @}*/
|
|
|
|
|
|
namespace internal {
|
|
/** \addtogroup rtos-internal-api */
|
|
/** @{*/
|
|
|
|
struct flags_check_capture {
|
|
uint32_t *flags;
|
|
uint32_t options;
|
|
uint32_t flags_wanted;
|
|
uint32_t result;
|
|
bool match;
|
|
};
|
|
|
|
bool non_rtos_check_flags(void *handle);
|
|
|
|
}
|
|
/** @}*/
|
|
}
|
|
#endif
|