thread.h

// 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 <tuple>
 
#include "pw_function/function.h"
#include "pw_thread/id.h"
#include "pw_thread/thread_core.h"
 
// clang-format off
// The backend's thread_native header must provide PW_THREAD_JOINING_ENABLED.
#include "pw_thread_backend/thread_native.h"
// clang-format on
 
namespace pw::thread {
 
class Options {
 protected:
  // We can't use `= default` here, because it allows to create an Options
  // instance in C++17 with `pw::thread::Options{}` syntax.
  constexpr Options() {}
};
 
class Thread {
 public:
  using native_handle_type = backend::NativeThreadHandle;
 
  Thread();
 
  Thread(const Options& options, Function<void()>&& entry);
 
  Thread(const Options& options, ThreadCore& thread_core);
 
  using ThreadRoutine = void (*)(void* arg);
 
  Thread(const Options& options, ThreadRoutine entry, void* arg = nullptr);
 
  Thread& operator=(Thread&& other);
 
  ~Thread();
 
  Thread(const Thread&) = delete;
  Thread(Thread&&) = delete;
  Thread& operator=(const Thread&) = delete;
 
  Id get_id() const;
 
  bool joinable() const { return get_id() != Id(); }
 
#if PW_THREAD_JOINING_ENABLED
  void join();
#else
  template <typename kUnusedType = void>
  void join() {
    static_assert(kJoiningEnabled<kUnusedType>,
                  "The selected pw_thread_THREAD backend does not have join() "
                  "enabled (AKA PW_THREAD_JOINING_ENABLED = 1)");
  }
#endif  // PW_THREAD_JOINING_ENABLED
 
  void detach();
 
  void swap(Thread& other);
 
  native_handle_type native_handle();
 
 private:
  template <typename...>
  static constexpr std::bool_constant<PW_THREAD_JOINING_ENABLED>
      kJoiningEnabled = {};
 
  // Note that just like std::thread, this is effectively just a pointer or
  // reference to the native thread -- this does not contain any memory needed
  // for the thread to execute.
  //
  // This may contain more than the native thread handle to enable functionality
  // which is not always available such as joining, which may require a
  // reference to a binary semaphore, or passing arguments to the thread's
  // function.
  backend::NativeThread native_type_;
};
 
}  // namespace pw::thread
 
#include "pw_thread_backend/thread_inline.h"