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 <type_traits>
 
#include "pw_function/function.h"
#include "pw_thread/attrs.h"
#include "pw_thread/context.h"
#include "pw_thread/id.h"
#include "pw_thread/native_options.h"
#include "pw_thread/options.h"
 
// clang-format off
// The backend's thread_native header must provide PW_THREAD_JOINING_ENABLED.
#include "pw_thread_backend/thread_native.h"  // IWYU pragma: export
// clang-format on
 
// Detect if the default "null" thread creation backend is seletecd.
#ifdef _PW_THREAD_GENERIC_CREATION_UNSUPPORTED
 
#define PW_THREAD_GENERIC_CREATION_IS_SUPPORTED 0
#undef _PW_THREAD_GENERIC_CREATION_UNSUPPORTED
 
#else
 
// Indicates whether generic thread creation is implemented.
// TODO: b/385440717 - Remove this flag when generic thread creation is
// implemented for all pw_thread backends.
#define PW_THREAD_GENERIC_CREATION_IS_SUPPORTED 1
 
#endif  // _PW_THREAD_GENERIC_CREATION_UNSUPPORTED
 
namespace pw {
namespace thread {
 
class Thread {
 public:
  using native_handle_type = backend::NativeThreadHandle;
 
  using id = ::pw::thread::backend::NativeId;
 
  Thread();
 
  Thread(const Options& options, Function<void()>&& entry);
 
  // Creates a thread with a ThreadContext associated with a ThreadAttrs.
  template <const ThreadAttrs& kAttributes>
  Thread(ThreadContextFor<kAttributes>& context, Function<void()>&& entry)
      : Thread(GetThreadOptions(context), std::move(entry)) {}
 
  // Creates a thread from context and attributes. Performs a runtime check
  // that the ThreadContext's stack is large enough, which can be avoided by
  // using one of the other constructors.
  template <size_t kStackSizeHintBytes>
  Thread(ThreadContext<kStackSizeHintBytes>& context,
         const ThreadAttrs& attributes,
         Function<void()>&& entry)
      : Thread(GetThreadOptions(context, attributes), std::move(entry)) {}
 
  // Creates a thread with the provided context and attributes. The
  // attributes must have a ThreadStack set.
  Thread(ThreadContext<>& context,
         const ThreadAttrs& attributes,
         Function<void()>&& entry)
      : Thread(GetThreadOptions(context, attributes), std::move(entry)) {}
 
  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..., bool kJoiningEnabled = false>
  void join() {
    static_assert(kJoiningEnabled,
                  "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:
  // 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 thread
 
using Thread = ::pw::thread::Thread;  // Must use `=` for Doxygen to find this.
 
}  // namespace pw
 
#include "pw_thread_backend/thread_inline.h"