1 /*
2  *  Copyright (c) 2011 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 // System independant wrapper for spawning threads
12 // Note: the spawned thread will loop over the callback function until stopped.
13 // Note: The callback function is expected to return every 2 seconds or more
14 // often.
15 
16 #ifndef WEBRTC_SYSTEM_WRAPPERS_INTERFACE_THREAD_WRAPPER_H_
17 #define WEBRTC_SYSTEM_WRAPPERS_INTERFACE_THREAD_WRAPPER_H_
18 
19 #include "common_types.h"
20 #include "typedefs.h"
21 
22 namespace webrtc {
23 // Object that will be passed by the spawned thread when it enters the callback
24 // function.
25 #define ThreadObj void*
26 
27 // Callback function that the spawned thread will enter once spawned.
28 // A return value of false is interpreted as that the function has no
29 // more work to do and that the thread can be released.
30 typedef  bool(*ThreadRunFunction)(ThreadObj);
31 
32 enum ThreadPriority
33 {
34     kLowPriority = 1,
35     kNormalPriority = 2,
36     kHighPriority = 3,
37     kHighestPriority = 4,
38     kRealtimePriority = 5
39 };
40 
41 class ThreadWrapper
42 {
43 public:
44     enum {kThreadMaxNameLength = 64};
45 
~ThreadWrapper()46     virtual ~ThreadWrapper() {};
47 
48     // Factory method. Constructor disabled.
49     //
50     // func        Pointer to a, by user, specified callback function.
51     // obj         Object associated with the thread. Passed in the callback
52     //             function.
53     // prio        Thread priority. May require root/admin rights.
54     // threadName  NULL terminated thread name, will be visable in the Windows
55     //             debugger.
56     static ThreadWrapper* CreateThread(ThreadRunFunction func = 0,
57                                        ThreadObj obj= 0,
58                                        ThreadPriority prio = kNormalPriority,
59                                        const char* threadName = 0);
60 
61     // Get the current thread's kernel thread ID.
62     static uint32_t GetThreadId();
63 
64     // Non blocking termination of the spawned thread. Note that it is not safe
65     // to delete this class until the spawned thread has been reclaimed.
66     virtual void SetNotAlive() = 0;
67 
68     // Spawns the thread. This will start the triggering of the callback
69     // function.
70     virtual bool Start(unsigned int& id) = 0;
71 
72     // Sets the threads CPU affinity. CPUs are listed 0 - (number of CPUs - 1).
73     // The numbers in processorNumbers specify which CPUs are allowed to run the
74     // thread. processorNumbers should not contain any duplicates and elements
75     // should be lower than (number of CPUs - 1). amountOfProcessors should be
76     // equal to the number of processors listed in processorNumbers
SetAffinity(const int *,const unsigned int)77     virtual bool SetAffinity(const int* /*processorNumbers*/,
78                              const unsigned int /*amountOfProcessors*/) {
79       return false;
80     }
81 
82     // Stops the spawned thread and waits for it to be reclaimed with a timeout
83     // of two seconds. Will return false if the thread was not reclaimed.
84     // Multiple tries to Stop are allowed (e.g. to wait longer than 2 seconds).
85     // It's ok to call Stop() even if the spawned thread has been reclaimed.
86     virtual bool Stop() = 0;
87 
88     // Stops the spawned thread dead in its tracks. Will likely result in a
89     // corrupt state. There should be an extremely good reason for even looking
90     // at this function. Can cause many problems deadlock being one of them.
Shutdown()91     virtual bool Shutdown() {return false;}
92 };
93 } // namespace webrtc
94 
95 #endif // WEBRTC_SYSTEM_WRAPPERS_INTERFACE_THREAD_WRAPPER_H_
96