diff options
Diffstat (limited to 'pw_thread/public/pw_thread/test_thread_context.h')
-rw-r--r-- | pw_thread/public/pw_thread/test_thread_context.h | 68 |
1 files changed, 68 insertions, 0 deletions
diff --git a/pw_thread/public/pw_thread/test_thread_context.h b/pw_thread/public/pw_thread/test_thread_context.h new file mode 100644 index 000000000..f4b8039f1 --- /dev/null +++ b/pw_thread/public/pw_thread/test_thread_context.h @@ -0,0 +1,68 @@ +// Copyright 2023 The Pigweed Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); you may not +// use this file except in compliance with the License. You may obtain a copy of +// the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +// License for the specific language governing permissions and limitations under +// the License. +#pragma once + +#include "pw_thread_backend/test_thread_context_native.h" + +namespace pw::thread::test { + +/// `TestThreadContext` is a facade class for creating threads for unit tests in +/// a platform independent way. To use it, set +/// `pw_thread_TEST_THREAD_CONTEXT_BACKEND` to a backend that implements the +/// `pw::thread::test::backend::TestThreadContextNative` class. +/// +/// To create a thread for unit testing, instantiate a `TestThreadContext`, then +/// call `options()` to obtain a `pw::thread::Options`. Use that `Options` to +/// start a `Thread`. Users must ensure the context's lifespan outlives the +/// thread it creates. Recycling or destroying the context is only allowed if +/// `join()` is called on the thread first. +/// +/// @code{.cpp} +/// pw::thread::test::TestThreadContext context; +/// pw::thread::Thread test_thread(context.options(), +/// ExampleThreadFunction); +/// @endcode +/// +/// Threads created with `TestThreadContext` cannot be configured in any way. +/// Backends should create threads with sufficient resources to execute typical +/// unit tests. Tests for complex scenarios or interactions where e.g. priority +/// matters are not portable, and `TestThreadContext` may not work for them. +/// Non-portable tests may include backend-specific headers and instantiate +/// thread options for their platforms as required. +/// +/// @note Developers should structure their logic so it can be tested without +/// spawning a thread. Unit tests should avoid spawning threads unless +/// absolutely necessary. +/// +/// @warning Threads using the `TestThreadContext` may only be detached if the +/// context has a static lifetime, meaning the context is both never re-used and +/// not destroyed before the end of the lifetime of the application. +class TestThreadContext { + public: + TestThreadContext() = default; + + TestThreadContext(const TestThreadContext&) = delete; + TestThreadContext& operator=(const TestThreadContext&) = delete; + + /// `pw::thread::test::TestThreadContext` returns a `pw::thread::Options` + /// associated with the this object, which can be used to contruct a thread. + /// + /// @return The default options for testing thread. + const Options& options() const { return context_.options(); } + + private: + backend::TestThreadContextNative context_; +}; + +} // namespace pw::thread::test |