Skip to content

Commit

Permalink
Rewrote thread deprecation notices to help migration
Browse files Browse the repository at this point in the history 
User feedback indicated that the previous deprecation notices
were confusing and mislead migration from the old style of thread
spawning.

The deprecation notices were updated to emphasize the replacement
functions, and examples of correct usage were added in the doxygen.
  • Loading branch information
@geky
geky committed Aug 26, 2016
1 parent 756a090 commit 022f821
Showing 1 changed file with 79 additions and 33 deletions.
112 changes: 79 additions & 33 deletions rtos/rtos/Thread.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,34 @@

namespace rtos {

/** The Thread class allow defining, creating, and controlling thread functions in the system. */
/** The Thread class allow defining, creating, and controlling thread functions in the system.
*
* Example:
* @code
* #include "mbed.h"
* #include "rtos.h"
*
* Thread thread;
* DigitalOut led1(LED1);
* volatile bool running = true;
*
* // Blink function toggles the led in a long running loop
* void blink(DigitalOut *led) {
* while (running) {
* *led = !*led;
* Thread::wait(1000);
* }
* }
*
* // Spawns a thread to run blink for 5 seconds
* int main() {
* thread.start(led1, blink);
* Thread::wait(5000);
* running = false;
* thread.join();
* }
* @endcode
*/
class Thread {
public:
/** Allocate a new thread without starting execution
Expand All @@ -52,15 +79,20 @@ class Thread {
@param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
@param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
@deprecated
Thread-spawning constructors hide errors and may lead to complex
program state when a thread is declared.
Thread-spawning constructors hide errors. Replaced by thread.start(task).
The explicit Thread::start member function should be used to spawn
a thread.
@code
Thread thread(priority, stack_size, stack_pointer);
osStatus status = thread.start(task);
if (status != osOK) {
error("oh no!");
}
@endcode
*/
MBED_DEPRECATED_SINCE("mbed-os-5.1",
"Thread-spawning constructors hide errors and may lead to complex "
"program state when a thread is declared")
"Thread-spawning constructors hide errors. "
"Replaced by thread.start(task).")
Thread(mbed::Callback<void()> task,
osPriority priority=osPriorityNormal,
uint32_t stack_size=DEFAULT_STACK_SIZE,
Expand All @@ -76,21 +108,26 @@ class Thread {
@param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
@param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
@deprecated
Thread-spawning constructors hide errors and may lead to complex
program state when a thread is declared.
Thread-spawning constructors hide errors. Replaced by thread.start(callback(argument, task)).
@code
Thread thread(priority, stack_size, stack_pointer);
The explicit Thread::start member function should be used to spawn
a thread.
osStatus status = thread.start(callback(argument, task));
if (status != osOK) {
error("oh no!");
}
@endcode
*/
template <typename T>
MBED_DEPRECATED_SINCE("mbed-os-5.1",
"Thread-spawning constructors hide errors and may lead to complex "
"program state when a thread is declared")
Thread(T *obj, void (T::*method)(),
"Thread-spawning constructors hide errors. "
"Replaced by thread.start(callback(argument, task)).")
Thread(T *argument, void (T::*task)(),
osPriority priority=osPriorityNormal,
uint32_t stack_size=DEFAULT_STACK_SIZE,
unsigned char *stack_pointer=NULL) {
constructor(mbed::callback(obj, method),
constructor(mbed::callback(argument, task),
priority, stack_size, stack_pointer);
}

Expand All @@ -102,21 +139,26 @@ class Thread {
@param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
@param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
@deprecated
Thread-spawning constructors hide errors and may lead to complex
program state when a thread is declared.
Thread-spawning constructors hide errors. Replaced by thread.start(callback(argument, task)).
The explicit Thread::start member function should be used to spawn
a thread.
@code
Thread thread(priority, stack_size, stack_pointer);
osStatus status = thread.start(callback(argument, task));
if (status != osOK) {
error("oh no!");
}
@endcode
*/
template <typename T>
MBED_DEPRECATED_SINCE("mbed-os-5.1",
"Thread-spawning constructors hide errors and may lead to complex "
"program state when a thread is declared")
Thread(T *obj, void (*method)(T *),
"Thread-spawning constructors hide errors. "
"Replaced by thread.start(callback(argument, task)).")
Thread(T *argument, void (*task)(T *),
osPriority priority=osPriorityNormal,
uint32_t stack_size=DEFAULT_STACK_SIZE,
unsigned char *stack_pointer=NULL) {
constructor(mbed::callback(obj, method),
constructor(mbed::callback(argument, task),
priority, stack_size, stack_pointer);
}

Expand All @@ -128,15 +170,20 @@ class Thread {
@param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
@param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
@deprecated
Thread-spawning constructors hide errors and may lead to complex
program state when a thread is declared.
Thread-spawning constructors hide errors. Replaced by thread.start(callback(argument, task)).
@code
Thread thread(priority, stack_size, stack_pointer);
The explicit Thread::start member function should be used to spawn
a thread.
osStatus status = thread.start(callback(argument, task));
if (status != osOK) {
error("oh no!");
}
@endcode
*/
MBED_DEPRECATED_SINCE("mbed-os-5.1",
"Thread-spawning constructors hide errors and may lead to complex "
"program state when a thread is declared")
"Thread-spawning constructors hide errors. "
"Replaced by thread.start(callback(argument, task)).")
Thread(void (*task)(void const *argument), void *argument=NULL,
osPriority priority=osPriorityNormal,
uint32_t stack_size=DEFAULT_STACK_SIZE,
Expand All @@ -156,13 +203,12 @@ class Thread {
@param method function to be executed by this thread.
@return status code that indicates the execution status of the function.
@deprecated
The start function does not support cv-qualifiers. Replaced by
start(callback(obj, method)).
The start function does not support cv-qualifiers. Replaced by start(callback(obj, method)).
*/
template <typename T, typename M>
MBED_DEPRECATED_SINCE("mbed-os-5.1",
"The start function does not support cv-qualifiers. Replaced by "
"start(callback(obj, method)).")
"The start function does not support cv-qualifiers. "
"Replaced by thread.start(callback(obj, method)).")
osStatus start(T *obj, M method) {
return start(mbed::callback(obj, method));
}
Expand Down

0 comments on commit 022f821

Please sign in to comment.