blob: 10d727c5b04ca3b7fad99e78506fe055dd5fd289 [file] [log] [blame]
henrike@webrtc.orgf0488722014-05-13 18:00:26 +00001/*
2 * Copyright 2004 The WebRTC Project Authors. All rights reserved.
3 *
4 * Use of this source code is governed by a BSD-style license
5 * that can be found in the LICENSE file in the root of the source
6 * tree. An additional intellectual property rights grant can be found
7 * in the file PATENTS. All contributing project authors may
8 * be found in the AUTHORS file in the root of the source tree.
9 */
10
11#ifndef WEBRTC_BASE_SIGNALTHREAD_H_
12#define WEBRTC_BASE_SIGNALTHREAD_H_
13
14#include <string>
15
16#include "webrtc/base/constructormagic.h"
magjedd9c7f8d2016-07-26 03:03:31 -070017#include "webrtc/base/nullsocketserver.h"
henrike@webrtc.orgf0488722014-05-13 18:00:26 +000018#include "webrtc/base/sigslot.h"
19#include "webrtc/base/thread.h"
20
21namespace rtc {
22
23///////////////////////////////////////////////////////////////////////////////
24// SignalThread - Base class for worker threads. The main thread should call
25// Start() to begin work, and then follow one of these models:
26// Normal: Wait for SignalWorkDone, and then call Release to destroy.
27// Cancellation: Call Release(true), to abort the worker thread.
28// Fire-and-forget: Call Release(false), which allows the thread to run to
29// completion, and then self-destruct without further notification.
30// Periodic tasks: Wait for SignalWorkDone, then eventually call Start()
31// again to repeat the task. When the instance isn't needed anymore,
32// call Release. DoWork, OnWorkStart and OnWorkStop are called again,
33// on a new thread.
34// The subclass should override DoWork() to perform the background task. By
35// periodically calling ContinueWork(), it can check for cancellation.
36// OnWorkStart and OnWorkDone can be overridden to do pre- or post-work
37// tasks in the context of the main thread.
38///////////////////////////////////////////////////////////////////////////////
39
40class SignalThread
41 : public sigslot::has_slots<>,
42 protected MessageHandler {
43 public:
magjedd9c7f8d2016-07-26 03:03:31 -070044 explicit SignalThread(bool use_socket_server = true);
henrike@webrtc.orgf0488722014-05-13 18:00:26 +000045
46 // Context: Main Thread. Call before Start to change the worker's name.
47 bool SetName(const std::string& name, const void* obj);
48
henrike@webrtc.orgf0488722014-05-13 18:00:26 +000049 // Context: Main Thread. Call to begin the worker thread.
50 void Start();
51
52 // Context: Main Thread. If the worker thread is not running, deletes the
53 // object immediately. Otherwise, asks the worker thread to abort processing,
54 // and schedules the object to be deleted once the worker exits.
55 // SignalWorkDone will not be signalled. If wait is true, does not return
56 // until the thread is deleted.
57 void Destroy(bool wait);
58
59 // Context: Main Thread. If the worker thread is complete, deletes the
60 // object immediately. Otherwise, schedules the object to be deleted once
61 // the worker thread completes. SignalWorkDone will be signalled.
62 void Release();
63
64 // Context: Main Thread. Signalled when work is complete.
65 sigslot::signal1<SignalThread *> SignalWorkDone;
66
67 enum { ST_MSG_WORKER_DONE, ST_MSG_FIRST_AVAILABLE };
68
69 protected:
kwiberg@webrtc.org67186fe2015-03-09 22:21:53 +000070 ~SignalThread() override;
henrike@webrtc.orgf0488722014-05-13 18:00:26 +000071
72 Thread* worker() { return &worker_; }
73
74 // Context: Main Thread. Subclass should override to do pre-work setup.
75 virtual void OnWorkStart() { }
76
77 // Context: Worker Thread. Subclass should override to do work.
78 virtual void DoWork() = 0;
79
80 // Context: Worker Thread. Subclass should call periodically to
81 // dispatch messages and determine if the thread should terminate.
82 bool ContinueWork();
83
84 // Context: Worker Thread. Subclass should override when extra work is
85 // needed to abort the worker thread.
86 virtual void OnWorkStop() { }
87
88 // Context: Main Thread. Subclass should override to do post-work cleanup.
89 virtual void OnWorkDone() { }
90
91 // Context: Any Thread. If subclass overrides, be sure to call the base
92 // implementation. Do not use (message_id < ST_MSG_FIRST_AVAILABLE)
kwiberg@webrtc.org67186fe2015-03-09 22:21:53 +000093 void OnMessage(Message* msg) override;
henrike@webrtc.orgf0488722014-05-13 18:00:26 +000094
95 private:
96 enum State {
97 kInit, // Initialized, but not started
98 kRunning, // Started and doing work
99 kReleasing, // Same as running, but to be deleted when work is done
100 kComplete, // Work is done
101 kStopping, // Work is being interrupted
102 };
103
104 class Worker : public Thread {
105 public:
magjedd9c7f8d2016-07-26 03:03:31 -0700106 explicit Worker(SignalThread* parent, bool use_socket_server)
107 : Thread(use_socket_server
108 ? SocketServer::CreateDefault()
109 : std::unique_ptr<SocketServer>(new NullSocketServer())),
110 parent_(parent) {}
kwiberg@webrtc.org67186fe2015-03-09 22:21:53 +0000111 ~Worker() override;
112 void Run() override;
henrike@webrtc.orgf0488722014-05-13 18:00:26 +0000113
114 private:
115 SignalThread* parent_;
116
henrikg3c089d72015-09-16 05:37:44 -0700117 RTC_DISALLOW_IMPLICIT_CONSTRUCTORS(Worker);
henrike@webrtc.orgf0488722014-05-13 18:00:26 +0000118 };
119
pbos@webrtc.orgd60d79a2014-09-24 07:10:57 +0000120 class SCOPED_LOCKABLE EnterExit {
henrike@webrtc.orgf0488722014-05-13 18:00:26 +0000121 public:
pbos@webrtc.orgd60d79a2014-09-24 07:10:57 +0000122 explicit EnterExit(SignalThread* t) EXCLUSIVE_LOCK_FUNCTION(t->cs_)
123 : t_(t) {
henrike@webrtc.orgf0488722014-05-13 18:00:26 +0000124 t_->cs_.Enter();
125 // If refcount_ is zero then the object has already been deleted and we
126 // will be double-deleting it in ~EnterExit()! (shouldn't happen)
127 ASSERT(t_->refcount_ != 0);
128 ++t_->refcount_;
129 }
pbos@webrtc.orgd60d79a2014-09-24 07:10:57 +0000130 ~EnterExit() UNLOCK_FUNCTION() {
henrike@webrtc.orgf0488722014-05-13 18:00:26 +0000131 bool d = (0 == --t_->refcount_);
132 t_->cs_.Leave();
133 if (d)
134 delete t_;
135 }
136
137 private:
138 SignalThread* t_;
139
henrikg3c089d72015-09-16 05:37:44 -0700140 RTC_DISALLOW_IMPLICIT_CONSTRUCTORS(EnterExit);
henrike@webrtc.orgf0488722014-05-13 18:00:26 +0000141 };
142
143 void Run();
144 void OnMainThreadDestroyed();
145
146 Thread* main_;
147 Worker worker_;
148 CriticalSection cs_;
149 State state_;
150 int refcount_;
151
henrikg3c089d72015-09-16 05:37:44 -0700152 RTC_DISALLOW_COPY_AND_ASSIGN(SignalThread);
henrike@webrtc.orgf0488722014-05-13 18:00:26 +0000153};
154
155///////////////////////////////////////////////////////////////////////////////
156
157} // namespace rtc
158
159#endif // WEBRTC_BASE_SIGNALTHREAD_H_