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
22namespace 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.
30typedef  bool(*ThreadRunFunction)(ThreadObj);
31
32enum ThreadPriority
33{
34    kLowPriority = 1,
35    kNormalPriority = 2,
36    kHighPriority = 3,
37    kHighestPriority = 4,
38    kRealtimePriority = 5
39};
40
41class ThreadWrapper
42{
43public:
44    enum {kThreadMaxNameLength = 64};
45
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
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.
91    virtual bool Shutdown() {return false;}
92};
93} // namespace webrtc
94
95#endif // WEBRTC_SYSTEM_WRAPPERS_INTERFACE_THREAD_WRAPPER_H_
96