pw_thread: add DetachedThread helper function
Adds the pw::thread::DetachedThread function as a helper to spawn
detached threads, where the user doesn't have to worry about the
thread handle and detaching it.
Change-Id: I179e342d8e0a79a08243a4438176b1249e13c660
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/42864
Reviewed-by: Wyatt Hepler <hepler@google.com>
Commit-Queue: Ewout van Bekkum <ewout@google.com>
diff --git a/pw_thread/BUILD b/pw_thread/BUILD
index 37ab883..c2b67b1 100644
--- a/pw_thread/BUILD
+++ b/pw_thread/BUILD
@@ -92,6 +92,7 @@
name = "thread_facade",
hdrs = [
"public/pw_thread/thread.h",
+ "public/pw_thread/detached_thread.h",
],
includes = ["public"],
deps = [
diff --git a/pw_thread/BUILD.gn b/pw_thread/BUILD.gn
index ccd04f3..f5cb98c 100644
--- a/pw_thread/BUILD.gn
+++ b/pw_thread/BUILD.gn
@@ -45,7 +45,10 @@
pw_facade("thread") {
backend = pw_thread_THREAD_BACKEND
public_configs = [ ":public_include_path" ]
- public = [ "public/pw_thread/thread.h" ]
+ public = [
+ "public/pw_thread/detached_thread.h",
+ "public/pw_thread/thread.h",
+ ]
public_deps = [
":id",
":thread_core",
diff --git a/pw_thread/docs.rst b/pw_thread/docs.rst
index 03b1a5a..c2b5ef3 100644
--- a/pw_thread/docs.rst
+++ b/pw_thread/docs.rst
@@ -112,6 +112,27 @@
A constructed ``pw::thread::Thread`` which represents a thread of execution
must be EITHER detached or joined, else the destructor will assert!
+DetachedThread
+==============
+To make it slightly easier and cleaner to spawn detached threads without having
+to worry about thread handles, a wrapper ``DetachedThread()`` function is
+provided which creates a ``Thread`` and immediately detaches it. For example
+instead of:
+
+.. code-block:: cpp
+
+ Thread(options, foo).detach();
+
+You can instead use this helper wrapper to:
+
+.. code-block:: cpp
+
+ DetachedThread(options, foo);
+
+The arguments are directly forwarded to the Thread constructor and ergo exactly
+match the Thread constuctor arguments for creating a thread of execution.
+
+
ThreadRoutine & ThreadCore
==========================
Threads must either be invoked through a
diff --git a/pw_thread/public/pw_thread/detached_thread.h b/pw_thread/public/pw_thread/detached_thread.h
new file mode 100644
index 0000000..03b43cc
--- /dev/null
+++ b/pw_thread/public/pw_thread/detached_thread.h
@@ -0,0 +1,39 @@
+// Copyright 2021 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/thread.h"
+
+namespace pw::thread {
+
+// Creates a detached a thread of execution.
+//
+// This is a very simple helper wrapper around Thread to help the common case of
+// creating a Thread which is immediately detached. For example instead of:
+//
+// Thread(options, foo).detach();
+//
+// You can instead use this helper wrapper to:
+//
+// DetachedThread(options, foo);
+//
+// The arguments are directly forwarded to the Thread constructor and ergo
+// exactly match the Thread constuctor arguments for creating a thread of
+// execution.
+template <class... Args>
+void DetachedThread(const Options& options, Args&&... args) {
+ Thread(options, std::forward<Args>(args)...).detach();
+}
+
+} // namespace pw::thread
