blob: f8b41d16b6b68791854d536275f7cb11f207ddbb [file] [log] [blame]
/*
* Copyright 2004 The WebRTC Project Authors. All rights reserved.
*
* Use of this source code is governed by a BSD-style license
* that can be found in the LICENSE file in the root of the source
* tree. An additional intellectual property rights grant can be found
* in the file PATENTS. All contributing project authors may
* be found in the AUTHORS file in the root of the source tree.
*/
#ifndef RTC_BASE_THREAD_H_
#define RTC_BASE_THREAD_H_
#include <stdint.h>
#include <list>
#include <memory>
#include <queue>
#include <string>
#include <type_traits>
#include <vector>
#if defined(WEBRTC_POSIX)
#include <pthread.h>
#endif
#include "api/function_view.h"
#include "api/task_queue/queued_task.h"
#include "api/task_queue/task_queue_base.h"
#include "rtc_base/constructor_magic.h"
#include "rtc_base/critical_section.h"
#include "rtc_base/location.h"
#include "rtc_base/message_handler.h"
#include "rtc_base/platform_thread_types.h"
#include "rtc_base/socket_server.h"
#include "rtc_base/system/rtc_export.h"
#include "rtc_base/thread_annotations.h"
#include "rtc_base/thread_message.h"
#if defined(WEBRTC_WIN)
#include "rtc_base/win32.h"
#endif
namespace rtc {
class Thread;
namespace rtc_thread_internal {
class MessageLikeTask : public MessageData {
public:
virtual void Run() = 0;
};
template <class FunctorT>
class MessageWithFunctor final : public MessageLikeTask {
public:
explicit MessageWithFunctor(FunctorT&& functor)
: functor_(std::forward<FunctorT>(functor)) {}
void Run() override { functor_(); }
private:
~MessageWithFunctor() override {}
typename std::remove_reference<FunctorT>::type functor_;
RTC_DISALLOW_COPY_AND_ASSIGN(MessageWithFunctor);
};
} // namespace rtc_thread_internal
class RTC_EXPORT ThreadManager {
public:
static const int kForever = -1;
// Singleton, constructor and destructor are private.
static ThreadManager* Instance();
static void Add(Thread* message_queue);
static void Remove(Thread* message_queue);
static void Clear(MessageHandler* handler);
// TODO(nisse): Delete alias, as soon as downstream code is updated.
static void ProcessAllMessageQueues() { ProcessAllMessageQueuesForTesting(); }
// For testing purposes, for use with a simulated clock.
// Ensures that all message queues have processed delayed messages
// up until the current point in time.
static void ProcessAllMessageQueuesForTesting();
Thread* CurrentThread();
void SetCurrentThread(Thread* thread);
// Allows changing the current thread, this is intended for tests where we
// want to simulate multiple threads running on a single physical thread.
void ChangeCurrentThreadForTest(Thread* thread);
// Returns a thread object with its thread_ ivar set
// to whatever the OS uses to represent the thread.
// If there already *is* a Thread object corresponding to this thread,
// this method will return that. Otherwise it creates a new Thread
// object whose wrapped() method will return true, and whose
// handle will, on Win32, be opened with only synchronization privileges -
// if you need more privilegs, rather than changing this method, please
// write additional code to adjust the privileges, or call a different
// factory method of your own devising, because this one gets used in
// unexpected contexts (like inside browser plugins) and it would be a
// shame to break it. It is also conceivable on Win32 that we won't even
// be able to get synchronization privileges, in which case the result
// will have a null handle.
Thread* WrapCurrentThread();
void UnwrapCurrentThread();
bool IsMainThread();
private:
ThreadManager();
~ThreadManager();
void SetCurrentThreadInternal(Thread* thread);
void AddInternal(Thread* message_queue);
void RemoveInternal(Thread* message_queue);
void ClearInternal(MessageHandler* handler);
void ProcessAllMessageQueuesInternal();
// This list contains all live Threads.
std::vector<Thread*> message_queues_ RTC_GUARDED_BY(crit_);
// Methods that don't modify the list of message queues may be called in a
// re-entrant fashion. "processing_" keeps track of the depth of re-entrant
// calls.
CriticalSection crit_;
size_t processing_ RTC_GUARDED_BY(crit_) = 0;
#if defined(WEBRTC_POSIX)
pthread_key_t key_;
#endif
#if defined(WEBRTC_WIN)
const DWORD key_;
#endif
// The thread to potentially autowrap.
const PlatformThreadRef main_thread_ref_;
RTC_DISALLOW_COPY_AND_ASSIGN(ThreadManager);
};
struct _SendMessage {
_SendMessage() {}
Thread* thread;
Message msg;
bool* ready;
};
// WARNING! SUBCLASSES MUST CALL Stop() IN THEIR DESTRUCTORS! See ~Thread().
class RTC_LOCKABLE RTC_EXPORT Thread : public webrtc::TaskQueueBase {
public:
static const int kForever = -1;
// Create a new Thread and optionally assign it to the passed
// SocketServer. Subclasses that override Clear should pass false for
// init_queue and call DoInit() from their constructor to prevent races
// with the ThreadManager using the object while the vtable is still
// being created.
explicit Thread(SocketServer* ss);
explicit Thread(std::unique_ptr<SocketServer> ss);
// Constructors meant for subclasses; they should call DoInit themselves and
// pass false for |do_init|, so that DoInit is called only on the fully
// instantiated class, which avoids a vptr data race.
Thread(SocketServer* ss, bool do_init);
Thread(std::unique_ptr<SocketServer> ss, bool do_init);
// NOTE: ALL SUBCLASSES OF Thread MUST CALL Stop() IN THEIR DESTRUCTORS (or
// guarantee Stop() is explicitly called before the subclass is destroyed).
// This is required to avoid a data race between the destructor modifying the
// vtable, and the Thread::PreRun calling the virtual method Run().
// NOTE: SUBCLASSES OF Thread THAT OVERRIDE Clear MUST CALL
// DoDestroy() IN THEIR DESTRUCTORS! This is required to avoid a data race
// between the destructor modifying the vtable, and the ThreadManager
// calling Clear on the object from a different thread.
~Thread() override;
static std::unique_ptr<Thread> CreateWithSocketServer();
static std::unique_ptr<Thread> Create();
static Thread* Current();
// Used to catch performance regressions. Use this to disallow blocking calls
// (Invoke) for a given scope. If a synchronous call is made while this is in
// effect, an assert will be triggered.
// Note that this is a single threaded class.
class ScopedDisallowBlockingCalls {
public:
ScopedDisallowBlockingCalls();
ScopedDisallowBlockingCalls(const ScopedDisallowBlockingCalls&) = delete;
ScopedDisallowBlockingCalls& operator=(const ScopedDisallowBlockingCalls&) =
delete;
~ScopedDisallowBlockingCalls();
private:
Thread* const thread_;
const bool previous_state_;
};
SocketServer* socketserver();
// Note: The behavior of Thread has changed. When a thread is stopped,
// futher Posts and Sends will fail. However, any pending Sends and *ready*
// Posts (as opposed to unexpired delayed Posts) will be delivered before
// Get (or Peek) returns false. By guaranteeing delivery of those messages,
// we eliminate the race condition when an MessageHandler and Thread
// may be destroyed independently of each other.
virtual void Quit();
virtual bool IsQuitting();
virtual void Restart();
// Not all message queues actually process messages (such as SignalThread).
// In those cases, it's important to know, before posting, that it won't be
// Processed. Normally, this would be true until IsQuitting() is true.
virtual bool IsProcessingMessagesForTesting();
// Get() will process I/O until:
// 1) A message is available (returns true)
// 2) cmsWait seconds have elapsed (returns false)
// 3) Stop() is called (returns false)
virtual bool Get(Message* pmsg,
int cmsWait = kForever,
bool process_io = true);
virtual bool Peek(Message* pmsg, int cmsWait = 0);
virtual void Post(const Location& posted_from,
MessageHandler* phandler,
uint32_t id = 0,
MessageData* pdata = nullptr,
bool time_sensitive = false);
virtual void PostDelayed(const Location& posted_from,
int cmsDelay,
MessageHandler* phandler,
uint32_t id = 0,
MessageData* pdata = nullptr);
virtual void PostAt(const Location& posted_from,
int64_t tstamp,
MessageHandler* phandler,
uint32_t id = 0,
MessageData* pdata = nullptr);
// TODO(honghaiz): Remove this when all the dependencies are removed.
virtual void PostAt(const Location& posted_from,
uint32_t tstamp,
MessageHandler* phandler,
uint32_t id = 0,
MessageData* pdata = nullptr);
virtual void Clear(MessageHandler* phandler,
uint32_t id = MQID_ANY,
MessageList* removed = nullptr);
virtual void Dispatch(Message* pmsg);
virtual void ReceiveSends();
// Amount of time until the next message can be retrieved
virtual int GetDelay();
bool empty() const { return size() == 0u; }
size_t size() const {
CritScope cs(&crit_); // msgq_.size() is not thread safe.
return msgq_.size() + dmsgq_.size() + (fPeekKeep_ ? 1u : 0u);
}
// Internally posts a message which causes the doomed object to be deleted
template <class T>
void Dispose(T* doomed) {
if (doomed) {
Post(RTC_FROM_HERE, nullptr, MQID_DISPOSE, new DisposeData<T>(doomed));
}
}
// When this signal is sent out, any references to this queue should
// no longer be used.
sigslot::signal0<> SignalQueueDestroyed;
bool IsCurrent() const;
// Sleeps the calling thread for the specified number of milliseconds, during
// which time no processing is performed. Returns false if sleeping was
// interrupted by a signal (POSIX only).
static bool SleepMs(int millis);
// Sets the thread's name, for debugging. Must be called before Start().
// If |obj| is non-null, its value is appended to |name|.
const std::string& name() const { return name_; }
bool SetName(const std::string& name, const void* obj);
// Starts the execution of the thread.
bool Start();
// Tells the thread to stop and waits until it is joined.
// Never call Stop on the current thread. Instead use the inherited Quit
// function which will exit the base Thread without terminating the
// underlying OS thread.
virtual void Stop();
// By default, Thread::Run() calls ProcessMessages(kForever). To do other
// work, override Run(). To receive and dispatch messages, call
// ProcessMessages occasionally.
virtual void Run();
virtual void Send(const Location& posted_from,
MessageHandler* phandler,
uint32_t id = 0,
MessageData* pdata = nullptr);
// Convenience method to invoke a functor on another thread. Caller must
// provide the |ReturnT| template argument, which cannot (easily) be deduced.
// Uses Send() internally, which blocks the current thread until execution
// is complete.
// Ex: bool result = thread.Invoke<bool>(RTC_FROM_HERE,
// &MyFunctionReturningBool);
// NOTE: This function can only be called when synchronous calls are allowed.
// See ScopedDisallowBlockingCalls for details.
// NOTE: Blocking invokes are DISCOURAGED, consider if what you're doing can
// be achieved with PostTask() and callbacks instead.
template <
class ReturnT,
typename = typename std::enable_if<!std::is_void<ReturnT>::value>::type>
ReturnT Invoke(const Location& posted_from, FunctionView<ReturnT()> functor) {
ReturnT result;
InvokeInternal(posted_from, [functor, &result] { result = functor(); });
return result;
}
template <
class ReturnT,
typename = typename std::enable_if<std::is_void<ReturnT>::value>::type>
void Invoke(const Location& posted_from, FunctionView<void()> functor) {
InvokeInternal(posted_from, functor);
}
// Posts a task to invoke the functor on |this| thread asynchronously, i.e.
// without blocking the thread that invoked PostTask(). Ownership of |functor|
// is passed and (usually, see below) destroyed on |this| thread after it is
// invoked.
// Requirements of FunctorT:
// - FunctorT is movable.
// - FunctorT implements "T operator()()" or "T operator()() const" for some T
// (if T is not void, the return value is discarded on |this| thread).
// - FunctorT has a public destructor that can be invoked from |this| thread
// after operation() has been invoked.
// - The functor must not cause the thread to quit before PostTask() is done.
//
// Destruction of the functor/task mimics what TaskQueue::PostTask does: If
// the task is run, it will be destroyed on |this| thread. However, if there
// are pending tasks by the time the Thread is destroyed, or a task is posted
// to a thread that is quitting, the task is destroyed immediately, on the
// calling thread. Destroying the Thread only blocks for any currently running
// task to complete. Note that TQ abstraction is even vaguer on how
// destruction happens in these cases, allowing destruction to happen
// asynchronously at a later time and on some arbitrary thread. So to ease
// migration, don't depend on Thread::PostTask destroying un-run tasks
// immediately.
//
// Example - Calling a class method:
// class Foo {
// public:
// void DoTheThing();
// };
// Foo foo;
// thread->PostTask(RTC_FROM_HERE, Bind(&Foo::DoTheThing, &foo));
//
// Example - Calling a lambda function:
// thread->PostTask(RTC_FROM_HERE,
// [&x, &y] { x.TrackComputations(y.Compute()); });
template <class FunctorT>
void PostTask(const Location& posted_from, FunctorT&& functor) {
Post(posted_from, GetPostTaskMessageHandler(), /*id=*/0,
new rtc_thread_internal::MessageWithFunctor<FunctorT>(
std::forward<FunctorT>(functor)));
}
template <class FunctorT>
void PostDelayedTask(const Location& posted_from,
FunctorT&& functor,
uint32_t milliseconds) {
PostDelayed(posted_from, milliseconds, GetPostTaskMessageHandler(),
/*id=*/0,
new rtc_thread_internal::MessageWithFunctor<FunctorT>(
std::forward<FunctorT>(functor)));
}
// From TaskQueueBase
void PostTask(std::unique_ptr<webrtc::QueuedTask> task) override;
void PostDelayedTask(std::unique_ptr<webrtc::QueuedTask> task,
uint32_t milliseconds) override;
void Delete() override;
// ProcessMessages will process I/O and dispatch messages until:
// 1) cms milliseconds have elapsed (returns true)
// 2) Stop() is called (returns false)
bool ProcessMessages(int cms);
// Returns true if this is a thread that we created using the standard
// constructor, false if it was created by a call to
// ThreadManager::WrapCurrentThread(). The main thread of an application
// is generally not owned, since the OS representation of the thread
// obviously exists before we can get to it.
// You cannot call Start on non-owned threads.
bool IsOwned();
// Expose private method IsRunning() for tests.
//
// DANGER: this is a terrible public API. Most callers that might want to
// call this likely do not have enough control/knowledge of the Thread in
// question to guarantee that the returned value remains true for the duration
// of whatever code is conditionally executing because of the return value!
bool RunningForTest() { return IsRunning(); }
// These functions are public to avoid injecting test hooks. Don't call them
// outside of tests.
// This method should be called when thread is created using non standard
// method, like derived implementation of rtc::Thread and it can not be
// started by calling Start(). This will set started flag to true and
// owned to false. This must be called from the current thread.
bool WrapCurrent();
void UnwrapCurrent();
// Sets the per-thread allow-blocking-calls flag to false; this is
// irrevocable. Must be called on this thread.
void DisallowBlockingCalls() { SetAllowBlockingCalls(false); }
#ifdef WEBRTC_ANDROID
// Sets the per-thread allow-blocking-calls flag to true, sidestepping the
// invariants upheld by DisallowBlockingCalls() and
// ScopedDisallowBlockingCalls. Must be called on this thread.
void DEPRECATED_AllowBlockingCalls() { SetAllowBlockingCalls(true); }
#endif
protected:
class PriorityQueue : public std::priority_queue<DelayedMessage> {
public:
container_type& container() { return c; }
void reheap() { make_heap(c.begin(), c.end(), comp); }
};
void DoDelayPost(const Location& posted_from,
int64_t cmsDelay,
int64_t tstamp,
MessageHandler* phandler,
uint32_t id,
MessageData* pdata);
// Perform initialization, subclasses must call this from their constructor
// if false was passed as init_queue to the Thread constructor.
void DoInit();
// Does not take any lock. Must be called either while holding crit_, or by
// the destructor (by definition, the latter has exclusive access).
void ClearInternal(MessageHandler* phandler,
uint32_t id,
MessageList* removed) RTC_EXCLUSIVE_LOCKS_REQUIRED(&crit_);
// Perform cleanup; subclasses must call this from the destructor,
// and are not expected to actually hold the lock.
void DoDestroy() RTC_EXCLUSIVE_LOCKS_REQUIRED(&crit_);
void WakeUpSocketServer();
// Same as WrapCurrent except that it never fails as it does not try to
// acquire the synchronization access of the thread. The caller should never
// call Stop() or Join() on this thread.
void SafeWrapCurrent();
// Blocks the calling thread until this thread has terminated.
void Join();
static void AssertBlockingIsAllowedOnCurrentThread();
friend class ScopedDisallowBlockingCalls;
CriticalSection* CritForTest() { return &crit_; }
private:
class QueuedTaskHandler final : public MessageHandler {
public:
void OnMessage(Message* msg) override;
};
// Sets the per-thread allow-blocking-calls flag and returns the previous
// value. Must be called on this thread.
bool SetAllowBlockingCalls(bool allow);
#if defined(WEBRTC_WIN)
static DWORD WINAPI PreRun(LPVOID context);
#else
static void* PreRun(void* pv);
#endif
// ThreadManager calls this instead WrapCurrent() because
// ThreadManager::Instance() cannot be used while ThreadManager is
// being created.
// The method tries to get synchronization rights of the thread on Windows if
// |need_synchronize_access| is true.
bool WrapCurrentWithThreadManager(ThreadManager* thread_manager,
bool need_synchronize_access);
// Return true if the thread is currently running.
bool IsRunning();
// Processes received "Send" requests. If |source| is not null, only requests
// from |source| are processed, otherwise, all requests are processed.
void ReceiveSendsFromThread(const Thread* source);
// If |source| is not null, pops the first "Send" message from |source| in
// |sendlist_|, otherwise, pops the first "Send" message of |sendlist_|.
// The caller must lock |crit_| before calling.
// Returns true if there is such a message.
bool PopSendMessageFromThread(const Thread* source, _SendMessage* msg);
void InvokeInternal(const Location& posted_from,
rtc::FunctionView<void()> functor);
// Returns a static-lifetime MessageHandler which runs message with
// MessageLikeTask payload data.
static MessageHandler* GetPostTaskMessageHandler();
bool fPeekKeep_;
Message msgPeek_;
MessageList msgq_ RTC_GUARDED_BY(crit_);
PriorityQueue dmsgq_ RTC_GUARDED_BY(crit_);
uint32_t dmsgq_next_num_ RTC_GUARDED_BY(crit_);
CriticalSection crit_;
bool fInitialized_;
bool fDestroyed_;
volatile int stop_;
// The SocketServer might not be owned by Thread.
SocketServer* const ss_;
// Used if SocketServer ownership lies with |this|.
std::unique_ptr<SocketServer> own_ss_;
std::list<_SendMessage> sendlist_;
std::string name_;
// TODO(tommi): Add thread checks for proper use of control methods.
// Ideally we should be able to just use PlatformThread.
#if defined(WEBRTC_POSIX)
pthread_t thread_ = 0;
#endif
#if defined(WEBRTC_WIN)
HANDLE thread_ = nullptr;
DWORD thread_id_ = 0;
#endif
// Indicates whether or not ownership of the worker thread lies with
// this instance or not. (i.e. owned_ == !wrapped).
// Must only be modified when the worker thread is not running.
bool owned_ = true;
// Only touched from the worker thread itself.
bool blocking_calls_allowed_ = true;
// Runs webrtc::QueuedTask posted to the Thread.
QueuedTaskHandler queued_task_handler_;
friend class ThreadManager;
RTC_DISALLOW_COPY_AND_ASSIGN(Thread);
};
// AutoThread automatically installs itself at construction
// uninstalls at destruction, if a Thread object is
// _not already_ associated with the current OS thread.
class AutoThread : public Thread {
public:
AutoThread();
~AutoThread() override;
private:
RTC_DISALLOW_COPY_AND_ASSIGN(AutoThread);
};
// AutoSocketServerThread automatically installs itself at
// construction and uninstalls at destruction. If a Thread object is
// already associated with the current OS thread, it is temporarily
// disassociated and restored by the destructor.
class AutoSocketServerThread : public Thread {
public:
explicit AutoSocketServerThread(SocketServer* ss);
~AutoSocketServerThread() override;
private:
rtc::Thread* old_thread_;
RTC_DISALLOW_COPY_AND_ASSIGN(AutoSocketServerThread);
};
// TODO(srte): Remove these when all dependencies has been updated.
using MessageQueue = Thread;
using MessageQueueManager = ThreadManager;
} // namespace rtc
#endif // RTC_BASE_THREAD_H_