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();

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::Thread thread;
etcpal::Error start_result = thread.Start(MyThreadFunction);
if (start_result)
{
  // Thread is running, yay!
}
else
{
  std::cout << "Error starting thread: " << start_result.ToString() << '\n';
}

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

etcpal::Thread thread;
etcpal::Error start_result = thread.SetName("My Thread")
                                    .SetPriority(4)
                                    .SetStackSize(4000)
                                    .Start(MyThreadFunction);

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

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.

IMPORTANT NOTES FOR ZEPHYR USERS: Some EtcPal features are dependent on Zephyr configuration see: Targeting Zephyr

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