Lines Matching full:thread
6 The ``pw_thread`` module contains utilities for thread creation and thread
13 Thread Sleeping
19 Blocks the execution of the current thread for at least the specified
27 **Precondition:** This can only be called from a thread, meaning the
32 Blocks the execution of the current thread until at least the specified
40 **Precondition:** This can only be called from a thread, meaning the
74 Thread Yielding
87 **Precondition:** This can only be called from a thread, meaning the
107 Thread Identification
109 The class ``pw::thread::Id`` is a lightweight, trivially copyable class that
110 serves as a unique identifier of Thread objects.
113 not represent any thread. Once a thread has finished, the value of its
114 Thread::id may be reused by another thread.
120 `std::thread::id <https://en.cppreference.com/w/cpp/thread/thread/id>`_, it is
124 A thread's identification (``pw::thread::Id``) can be acquired only in C++ in
127 1) Using the ``pw::thread::Thread`` handle's ``pw::thread::Id get_id() const``
129 2) While executing the thread using
130 ``pw::thread::Id pw::this_thread::get_id() noexcept``.
132 .. cpp:function:: pw::thread::Id pw::this_thread::get_id() noexcept
134 This is thread safe, not IRQ safe. It is implementation defined whether this
145 const pw::thread::Id my_id = pw::this_thread::get_id();
149 .. _module-pw_thread-thread-creation:
152 Thread Creation
154 The class ``pw::thread::Thread`` can represent a single thread of execution.
157 The Thread's API is C++11 STL
158 `std::thread <https://en.cppreference.com/w/cpp/thread/thread>`_ like, meaning
159 the object is effectively a thread handle and not an object which contains the
160 thread's context. Unlike ``std::thread``, the API requires
161 ``pw::thread::Options`` as an argument and is limited to only work with
162 ``pw::thread::ThreadCore`` objects and functions which match the
163 ``pw::thread::Thread::ThreadRoutine`` signature.
165 We recognize that the C++11's STL ``std::thread``` API has some drawbacks where
166 it is easy to forget to join or detach the thread handle. Because of this, we
167 offer helper wrappers like the ``pw::thread::DetachedThread``. Soon we will
168 extend this by also adding a ``pw::thread::JoiningThread`` helper wrapper which
173 thread object (pending any OS scheduling delays), starting at the top-level
179 Thread objects may also be in the state that does not represent any thread
180 (after default construction, move from, detach, or join), and a thread of
181 execution may be not associated with any thread objects (after detach).
183 No two Thread objects may represent the same thread of execution; Thread is
217 The ``pw::thread::Options`` contains the parameters or attributes needed for a
218 thread to start.
227 but may contain things like the thread name, priority, scheduling policy,
229 Context (the collection of memory allocations needed for a thread to run).
232 All ``pw::thread::Thread`` instances must be explicitly ``join()``'d or
233 ``detach()``'d through the run-time Thread API.
240 Options must not contain any memory needed for a thread to run (TCB,
242 starting a thread.
248 constructor to be public (which is not the case for the ``thread::Options``) for
251 Please see the thread creation backend documentation for how their Options work.
253 Portable Thread Creation
255 Due to the fact that ``pw::thread::Options`` cannot be created in portable code,
256 some extra work must be done in order to permit portable thread creation.
257 Namely, a reference to the portable ``pw::thread::Options`` base class interface
263 on both the host and on a device with the device's exact thread options.
270 As an example, let's say we want to create a thread on the host and on a device
279 #include "pw_thread/thread.h"
283 const pw::thread::Options& HellowWorldThreadOptions();
288 the thread backend. For example for the STL the backend's ``stl_threads.cc``
299 const pw::thread::Options& HelloWorldThreadOptions() {
300 static constexpr auto options = pw::thread::stl::Options();
321 const pw::thread::Options& HelloWorldThreadOptions() {
323 pw::thread::freertos::Options()
335 The ``Thread::detach()`` API is always available, to let you separate the
336 thread of execution from the thread object, allowing execution to continue
339 The joining API, more specifically ``Thread::join()``, is conditionally
340 available depending on the selected backend for thread creation and how it is
344 ``pw_thread/thread.h`` can use this macro if needed.
346 Please see the selected thread creation backend documentation for how to
350 A constructed ``pw::thread::Thread`` which represents a thread of execution
356 to worry about thread handles, a wrapper ``DetachedThread()`` function is
357 provided which creates a ``Thread`` and immediately detaches it. For example
362 Thread(options, foo).detach();
370 The arguments are directly forwarded to the Thread constructor and ergo exactly
371 match the Thread constuctor arguments for creating a thread of execution.
377 ``pw::thread::Thread::ThreadRoutine``` style function or implement the
378 ``pw::thread::ThreadCore`` interface.
382 namespace pw::thread {
385 using Thread::ThreadRoutine = void (*)(void* arg);
399 } // namespace pw::thread;
402 To use the ``pw::thread::Thread::ThreadRoutine``, your function must have the
411 to ensure the dispatching closure is not destructed before the thread is
427 // Now use the lambda closure as the thread entry, passing the foo's
429 Thread thread(options, invoke_foo_do_bar, &foo);
430 thread.detach();
433 Alternatively, the aforementioned ``pw::thread::ThreadCore`` interface can be
435 ``void ThreadCore::Run();`` method. This makes it easier to create a thread, as
447 // Now create the thread, using foo directly.
448 Thread(options, foo).detach();
451 Because the thread may start after the pw::Thread creation, an object which
452 implements the ThreadCore MUST meet or exceed the lifetime of its thread of
456 Thread Iteration
462 Calls the provided callback for each thread that has not been joined/deleted.
470 a runtime capture of thread information.
473 Thread Snapshot Service
476 (``:thread_snapshot_service``) that enables thread info capture of
478 optimization of stack usage by providing an overview of thread information,
479 including thread name, stack bounds, and peak stack usage.
483 for a specific thread, filtering by name
484 (``ThreadSnapshotService::GetPeakStackUsage(name=b"/* thread name */")``).
485 Thread information capture relies on the thread iteration facade which will
493 1. Create an instance of ``pw::thread::proto::ThreadSnapshotServiceBuffer``.
495 size buffers required for a ``ThreadSnapshotService``. If no thread count
512 // Thread snapshot service builder instance.
513 pw::thread::proto::ThreadSnapshotServiceBuffer</*num threads*/>
531 The max number of threads to use by default for thread snapshot service.
542 properly before using this service.** Please see the thread iteration
549 helper functions for populating a ``pw::thread::Thread`` proto. Some of these
550 are directly integrated into the RTOS thread backends to simplify the thread
556 bounds) into a ``pw::thread::Thread`` proto. After the stack bounds are
557 captured, execution is passed off to the thread stack collection callback to
559 thread name: that metadata is only required in cases where a stack overflow or
564 Threads captured as a Thread proto message can be dumped or further analyzed
566 pw_snapshot's processor tool to automatically provide rich thread state dumps.
569 currently running thread and produce symbolized thread dumps.