pw_thread_freertos/thread.cc - pigweed/pigweed - Git at Google

 // Copyright 2020 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.
 #include "pw_thread/thread.h"

 #include "FreeRTOS.h"
 #include "pw_assert/check.h"
 #include "pw_preprocessor/compiler.h"
 #include "pw_thread/deprecated_or_new_thread_function.h"
 #include "pw_thread/id.h"
 #include "pw_thread_freertos/config.h"
 #include "pw_thread_freertos/context.h"
 #include "pw_thread_freertos/options.h"
 #include "task.h"

 using pw::thread::freertos::Context;

 namespace pw::thread {
 namespace {

 #if (INCLUDE_xTaskGetSchedulerState != 1) && (configUSE_TIMERS != 1)
 #error "xTaskGetSchedulerState is required for pw::thread::Thread"
 #endif

 #if PW_THREAD_JOINING_ENABLED
 constexpr EventBits_t kThreadDoneBit = 1 << 0;
 #endif  // PW_THREAD_JOINING_ENABLED
 }  // namespace

 void Context::ThreadEntryPoint(void* void_context_ptr) {
   Context& context = *static_cast<Context*>(void_context_ptr);

   // Invoke the user's thread function. This may never return.
   context.fn_();
   context.fn_ = nullptr;

   // Use a task only critical section to guard against join() and detach().
   vTaskSuspendAll();
   if (context.detached()) {
     // There is no threadsafe way to re-use detached threads, as there's no way
     // to signal the vTaskDelete success. Joining MUST be used for this.
     // However to enable unit test coverage we go ahead and clear this.
     context.set_task_handle(nullptr);

 #if PW_THREAD_JOINING_ENABLED
     // If the thread handle was detached before the thread finished execution,
     // i.e. got here, then we are responsible for cleaning up the join event
     // group.
     vEventGroupDelete(
         reinterpret_cast<EventGroupHandle_t>(&context.join_event_group()));
 #endif  // PW_THREAD_JOINING_ENABLED

 #if PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
     // The thread was detached before the task finished, free any allocations
     // it ran on.
     if (context.dynamically_allocated()) {
       delete &context;
     }
 #endif  // PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED

     // Re-enable the scheduler before we delete this execution.
     xTaskResumeAll();
     vTaskDelete(nullptr);
     PW_UNREACHABLE;
   }

   // Otherwise the task finished before the thread was detached or joined, defer
   // cleanup to Thread's join() or detach().
   context.set_thread_done();
   xTaskResumeAll();

 #if PW_THREAD_JOINING_ENABLED
   xEventGroupSetBits(
       reinterpret_cast<EventGroupHandle_t>(&context.join_event_group()),
       kThreadDoneBit);
 #endif  // PW_THREAD_JOINING_ENABLED

   while (true) {
 #if INCLUDE_vTaskSuspend == 1
     // Use indefinite suspension when available.
     vTaskSuspend(nullptr);
 #else
     vTaskDelay(portMAX_DELAY);
 #endif  // INCLUDE_vTaskSuspend == 1
   }
   PW_UNREACHABLE;
 }

 void Context::TerminateThread(Context& context) {
   // Stop the other task first.
   PW_DCHECK_NOTNULL(context.task_handle(), "We shall not delete ourselves!");
   vTaskDelete(context.task_handle());

   // Mark the context as unused for potential later re-use.
   context.set_task_handle(nullptr);

 #if PW_THREAD_JOINING_ENABLED
   // Just in case someone abused our API, ensure their use of the event group is
   // properly handled by the kernel regardless.
   vEventGroupDelete(
       reinterpret_cast<EventGroupHandle_t>(&context.join_event_group()));
 #endif  // PW_THREAD_JOINING_ENABLED

 #if PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
   // Then free any allocations it ran on.
   if (context.dynamically_allocated()) {
     delete &context;
   }
 #endif  // PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
 }

 void Context::AddToEventGroup() {
 #if PW_THREAD_JOINING_ENABLED
   const EventGroupHandle_t event_group_handle =
       xEventGroupCreateStatic(&join_event_group());
   PW_DCHECK_PTR_EQ(event_group_handle,
                    &join_event_group(),
                    "Failed to create the joining event group");
 #endif  // PW_THREAD_JOINING_ENABLED
 }

 void Context::CreateThread(const freertos::Options& options,
                            DeprecatedOrNewThreadFn&& thread_fn,
                            Context*& native_type_out) {
   TaskHandle_t task_handle;
   if (options.static_context() != nullptr) {
     // Use the statically allocated context.
     native_type_out = options.static_context();
     // Can't use a context more than once.
     PW_DCHECK_PTR_EQ(native_type_out->task_handle(), nullptr);
     // Reset the state of the static context in case it was re-used.
     native_type_out->set_detached(false);
     native_type_out->set_thread_done(false);
     native_type_out->AddToEventGroup();

     // In order to support functions which return and joining, a delegate is
     // deep copied into the context with a small wrapping function to actually
     // invoke the task with its arg.
     native_type_out->set_thread_routine(std::move(thread_fn));
     task_handle = xTaskCreateStatic(Context::ThreadEntryPoint,
                                     options.name(),
                                     options.static_context()->stack().size(),
                                     native_type_out,
                                     options.priority(),
                                     options.static_context()->stack().data(),
                                     &options.static_context()->tcb());
   } else {
 #if !PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
     PW_CRASH(
         "dynamic thread allocations are not enabled and no static_context "
         "was provided");
 #else   // PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
     // Dynamically allocate the context and the task.
     native_type_out = new pw::thread::freertos::Context();
     native_type_out->set_dynamically_allocated();
     native_type_out->AddToEventGroup();

     // In order to support functions which return and joining, a delegate is
     // deep copied into the context with a small wrapping function to actually
     // invoke the task with its arg.
     native_type_out->set_thread_routine(std::move(thread_fn));
     const BaseType_t result = xTaskCreate(Context::ThreadEntryPoint,
                                           options.name(),
                                           options.stack_size_words(),
                                           native_type_out,
                                           options.priority(),
                                           &task_handle);

     // Ensure it succeeded.
     PW_CHECK_UINT_EQ(result, pdPASS);
 #endif  // !PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
   }
   PW_CHECK_NOTNULL(task_handle);  // Ensure it succeeded.
   native_type_out->set_task_handle(task_handle);
 }

 Thread::Thread(const thread::Options& facade_options, Function<void()>&& entry)
     : native_type_(nullptr) {
   // Cast the generic facade options to the backend specific option of which
   // only one type can exist at compile time.
   auto options = static_cast<const freertos::Options&>(facade_options);
   Context::CreateThread(options, std::move(entry), native_type_);
 }

 Thread::Thread(const thread::Options& facade_options,
                ThreadRoutine routine,
                void* arg)
     : native_type_(nullptr) {
   // Cast the generic facade options to the backend specific option of which
   // only one type can exist at compile time.
   auto options = static_cast<const freertos::Options&>(facade_options);
   Context::CreateThread(
       options, DeprecatedFnPtrAndArg{routine, arg}, native_type_);
 }

 void Thread::detach() {
   PW_CHECK(joinable());

   // xTaskResumeAll() can only be used after the scheduler has been started.
   const bool scheduler_initialized =
       xTaskGetSchedulerState() != taskSCHEDULER_NOT_STARTED;

   if (scheduler_initialized) {
     // We don't want to individually suspend and resume this task using
     // vTaskResume() as that can cause tasks to prematurely wake up and return
     // from blocking APIs (b/303885539).
     vTaskSuspendAll();
   }
   native_type_->set_detached();
   const bool thread_done = native_type_->thread_done();
   if (scheduler_initialized) {
     xTaskResumeAll();
   }

   if (thread_done) {
     // The task finished (hit end of Context::ThreadEntryPoint) before we
     // invoked detach, clean up the thread.
     Context::TerminateThread(*native_type_);
   } else {
     // We're detaching before the task finished, defer cleanup to the task at
     // the end of Context::ThreadEntryPoint.
   }

   // Update to no longer represent a thread of execution.
   native_type_ = nullptr;
 }

 #if PW_THREAD_JOINING_ENABLED
 void Thread::join() {
   PW_CHECK(joinable());
   PW_CHECK(this_thread::get_id() != get_id());

   // Wait indefinitely until kThreadDoneBit is set.
   while (xEventGroupWaitBits(reinterpret_cast<EventGroupHandle_t>(
                                  &native_type_->join_event_group()),
                              kThreadDoneBit,
                              pdTRUE,   // Clear the bits.
                              pdFALSE,  // Any bits is fine, N/A.
                              portMAX_DELAY) != kThreadDoneBit) {
   }

   // No need for a critical section here as the thread at this point is
   // waiting to be terminated.
   Context::TerminateThread(*native_type_);

   // Update to no longer represent a thread of execution.
   native_type_ = nullptr;
 }
 #endif  // PW_THREAD_JOINING_ENABLED

 }  // namespace pw::thread
	// Copyright 2020 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.
	#include "pw_thread/thread.h"

	#include "FreeRTOS.h"
	#include "pw_assert/check.h"
	#include "pw_preprocessor/compiler.h"
	#include "pw_thread/deprecated_or_new_thread_function.h"
	#include "pw_thread/id.h"
	#include "pw_thread_freertos/config.h"
	#include "pw_thread_freertos/context.h"
	#include "pw_thread_freertos/options.h"
	#include "task.h"

	using pw::thread::freertos::Context;

	namespace pw::thread {
	namespace {

	#if (INCLUDE_xTaskGetSchedulerState != 1) && (configUSE_TIMERS != 1)
	#error "xTaskGetSchedulerState is required for pw::thread::Thread"
	#endif

	#if PW_THREAD_JOINING_ENABLED
	constexpr EventBits_t kThreadDoneBit = 1 << 0;
	#endif // PW_THREAD_JOINING_ENABLED
	} // namespace

	void Context::ThreadEntryPoint(void* void_context_ptr) {
	Context& context = static_cast<Context>(void_context_ptr);

	// Invoke the user's thread function. This may never return.
	context.fn_();
	context.fn_ = nullptr;

	// Use a task only critical section to guard against join() and detach().
	vTaskSuspendAll();
	if (context.detached()) {
	// There is no threadsafe way to re-use detached threads, as there's no way
	// to signal the vTaskDelete success. Joining MUST be used for this.
	// However to enable unit test coverage we go ahead and clear this.
	context.set_task_handle(nullptr);

	#if PW_THREAD_JOINING_ENABLED
	// If the thread handle was detached before the thread finished execution,
	// i.e. got here, then we are responsible for cleaning up the join event
	// group.
	vEventGroupDelete(
	reinterpret_cast<EventGroupHandle_t>(&context.join_event_group()));
	#endif // PW_THREAD_JOINING_ENABLED

	#if PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
	// The thread was detached before the task finished, free any allocations
	// it ran on.
	if (context.dynamically_allocated()) {
	delete &context;
	}
	#endif // PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED

	// Re-enable the scheduler before we delete this execution.
	xTaskResumeAll();
	vTaskDelete(nullptr);
	PW_UNREACHABLE;
	}

	// Otherwise the task finished before the thread was detached or joined, defer
	// cleanup to Thread's join() or detach().
	context.set_thread_done();
	xTaskResumeAll();

	#if PW_THREAD_JOINING_ENABLED
	xEventGroupSetBits(
	reinterpret_cast<EventGroupHandle_t>(&context.join_event_group()),
	kThreadDoneBit);
	#endif // PW_THREAD_JOINING_ENABLED

	while (true) {
	#if INCLUDE_vTaskSuspend == 1
	// Use indefinite suspension when available.
	vTaskSuspend(nullptr);
	#else
	vTaskDelay(portMAX_DELAY);
	#endif // INCLUDE_vTaskSuspend == 1
	}
	PW_UNREACHABLE;
	}

	void Context::TerminateThread(Context& context) {
	// Stop the other task first.
	PW_DCHECK_NOTNULL(context.task_handle(), "We shall not delete ourselves!");
	vTaskDelete(context.task_handle());

	// Mark the context as unused for potential later re-use.
	context.set_task_handle(nullptr);

	#if PW_THREAD_JOINING_ENABLED
	// Just in case someone abused our API, ensure their use of the event group is
	// properly handled by the kernel regardless.
	vEventGroupDelete(
	reinterpret_cast<EventGroupHandle_t>(&context.join_event_group()));
	#endif // PW_THREAD_JOINING_ENABLED

	#if PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
	// Then free any allocations it ran on.
	if (context.dynamically_allocated()) {
	delete &context;
	}
	#endif // PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
	}

	void Context::AddToEventGroup() {
	#if PW_THREAD_JOINING_ENABLED
	const EventGroupHandle_t event_group_handle =
	xEventGroupCreateStatic(&join_event_group());
	PW_DCHECK_PTR_EQ(event_group_handle,
	&join_event_group(),
	"Failed to create the joining event group");
	#endif // PW_THREAD_JOINING_ENABLED
	}

	void Context::CreateThread(const freertos::Options& options,
	DeprecatedOrNewThreadFn&& thread_fn,
	Context*& native_type_out) {
	TaskHandle_t task_handle;
	if (options.static_context() != nullptr) {
	// Use the statically allocated context.
	native_type_out = options.static_context();
	// Can't use a context more than once.
	PW_DCHECK_PTR_EQ(native_type_out->task_handle(), nullptr);
	// Reset the state of the static context in case it was re-used.
	native_type_out->set_detached(false);
	native_type_out->set_thread_done(false);
	native_type_out->AddToEventGroup();

	// In order to support functions which return and joining, a delegate is
	// deep copied into the context with a small wrapping function to actually
	// invoke the task with its arg.
	native_type_out->set_thread_routine(std::move(thread_fn));
	task_handle = xTaskCreateStatic(Context::ThreadEntryPoint,
	options.name(),
	options.static_context()->stack().size(),
	native_type_out,
	options.priority(),
	options.static_context()->stack().data(),
	&options.static_context()->tcb());
	} else {
	#if !PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
	PW_CRASH(
	"dynamic thread allocations are not enabled and no static_context "
	"was provided");
	#else // PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
	// Dynamically allocate the context and the task.
	native_type_out = new pw::thread::freertos::Context();
	native_type_out->set_dynamically_allocated();
	native_type_out->AddToEventGroup();

	// In order to support functions which return and joining, a delegate is
	// deep copied into the context with a small wrapping function to actually
	// invoke the task with its arg.
	native_type_out->set_thread_routine(std::move(thread_fn));
	const BaseType_t result = xTaskCreate(Context::ThreadEntryPoint,
	options.name(),
	options.stack_size_words(),
	native_type_out,
	options.priority(),
	&task_handle);

	// Ensure it succeeded.
	PW_CHECK_UINT_EQ(result, pdPASS);
	#endif // !PW_THREAD_FREERTOS_CONFIG_DYNAMIC_ALLOCATION_ENABLED
	}
	PW_CHECK_NOTNULL(task_handle); // Ensure it succeeded.
	native_type_out->set_task_handle(task_handle);
	}

	Thread::Thread(const thread::Options& facade_options, Function<void()>&& entry)
	: native_type_(nullptr) {
	// Cast the generic facade options to the backend specific option of which
	// only one type can exist at compile time.
	auto options = static_cast<const freertos::Options&>(facade_options);
	Context::CreateThread(options, std::move(entry), native_type_);
	}

	Thread::Thread(const thread::Options& facade_options,
	ThreadRoutine routine,
	void* arg)
	: native_type_(nullptr) {
	// Cast the generic facade options to the backend specific option of which
	// only one type can exist at compile time.
	auto options = static_cast<const freertos::Options&>(facade_options);
	Context::CreateThread(
	options, DeprecatedFnPtrAndArg{routine, arg}, native_type_);
	}

	void Thread::detach() {
	PW_CHECK(joinable());

	// xTaskResumeAll() can only be used after the scheduler has been started.
	const bool scheduler_initialized =
	xTaskGetSchedulerState() != taskSCHEDULER_NOT_STARTED;

	if (scheduler_initialized) {
	// We don't want to individually suspend and resume this task using
	// vTaskResume() as that can cause tasks to prematurely wake up and return
	// from blocking APIs (b/303885539).
	vTaskSuspendAll();
	}
	native_type_->set_detached();
	const bool thread_done = native_type_->thread_done();
	if (scheduler_initialized) {
	xTaskResumeAll();
	}

	if (thread_done) {
	// The task finished (hit end of Context::ThreadEntryPoint) before we
	// invoked detach, clean up the thread.
	Context::TerminateThread(*native_type_);
	} else {
	// We're detaching before the task finished, defer cleanup to the task at
	// the end of Context::ThreadEntryPoint.
	}

	// Update to no longer represent a thread of execution.
	native_type_ = nullptr;
	}

	#if PW_THREAD_JOINING_ENABLED
	void Thread::join() {
	PW_CHECK(joinable());
	PW_CHECK(this_thread::get_id() != get_id());

	// Wait indefinitely until kThreadDoneBit is set.
	while (xEventGroupWaitBits(reinterpret_cast<EventGroupHandle_t>(
	&native_type_->join_event_group()),
	kThreadDoneBit,
	pdTRUE, // Clear the bits.
	pdFALSE, // Any bits is fine, N/A.
	portMAX_DELAY) != kThreadDoneBit) {
	}

	// No need for a critical section here as the thread at this point is
	// waiting to be terminated.
	Context::TerminateThread(*native_type_);

	// Update to no longer represent a thread of execution.
	native_type_ = nullptr;
	}
	#endif // PW_THREAD_JOINING_ENABLED

	} // namespace pw::thread