EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
thread (Threading)

Overview

C++ utilities for the thread (Threading) module.

Provides a thread class Thread which is similar to std::thread, with the key advantage that it will work on any threaded platform that EtcPal is ported for, including the embedded RTOS platforms. If your application or library does not need to run on these platforms, consider using std::thread instead (or in >= C++20, std::jthread, which more closely matches the behavior of this class).

To start the thread with default parameters, you can use the constructor:

void MyThreadFunction()
{
std::cout << "Hello from a thread!\n";
}
etcpal::Thread thread(MyThreadFunction); // Thread is now running
// Thread will be automatically joined when thread goes out of scope, or join it explicitly:
thread.Join();
A thread class, modeled after std::thread.
Definition: thread.h:143

The value constructor will throw an etcpal::Error object if the thread fails to start for any reason. To avoid an exception-handling approach, you can default-construct and use the Start() function:

etcpal::Error start_result = thread.Start(MyThreadFunction);
if (start_result)
{
// Thread is running, yay!
}
else
{
std::cout << "Error starting thread: " << start_result.ToString() << '\n';
}
A wrapper class for the EtcPal error type.
Definition: error.h:94
std::string ToString() const
Get a descriptive string for this Error as a std::string.
Definition: error.h:144
Error Start(Function &&func, Args &&... args)
Associate this thread object with a new thread of execution.
Definition: thread.h:425

This approach also lets you set non-default thread parameters before starting; method-chaining syntax is available on these setters:

etcpal::Error start_result = thread.SetName("My Thread")
.SetStackSize(4000)
.Start(MyThreadFunction);
Thread & SetStackSize(unsigned int stack_size) noexcept
Set the stack size of this thread in bytes.
Definition: thread.h:341
Thread & SetPriority(unsigned int priority) noexcept
Set the priority of this thread.
Definition: thread.h:328
Thread & SetName(const char *name) noexcept
Set the name of this thread.
Definition: thread.h:355

Pass arguments to your thread function, which will be stored on the heap:

void MyThreadFunction(int value)
{
std::cout << "The value is " << value << ".\n";
}
etcpal::Thread thread(MyThreadFunction, 5); // Thread will print "The value is 5."

You can even use lambdas for quick-and-dirty operations:

int value = 42;
etcpal::Thread thread([=]() { std::cout << "The value is " << value << '\n'; });

The Thread class also provides static Sleep() functions, which can be used as a platform-neutral sleep.

etcpal::Thread::Sleep(20); // Sleep for 20 milliseconds
etcpal::Thread::Sleep(std::chrono::seconds(2)); // Sleep for 2 seconds
// In a C++14 or greater environment, you can also...
using namespace std::chrono_literals;
etcpal::Thread::Sleep(1min); // Sleep for 1 minute
static void Sleep(unsigned int ms) noexcept
Blocks the current thread for the specified number of milliseconds.
Definition: thread.h:491

IMPORTANT NOTE FOR RTOS USERS: The EtcPal threading API does not initialize the scheduler on real-time systems (e.g. it does not call vTaskStartScheduler() on FreeRTOS or _mqx() on MQX). The application writer is responsible for managing the interaction between starting the scheduler and starting EtcPal threads, just like when starting native RTOS tasks.

Data Structures

class  Thread
 A thread class, modeled after std::thread. More...