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