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 "webrtc/common_types.h"
20#include "webrtc/typedefs.h"
21
22namespace webrtc {
23
24// Object that will be passed by the spawned thread when it enters the callback
25// function.
26#define ThreadObj void*
27
28// Callback function that the spawned thread will enter once spawned.
29// A return value of false is interpreted as that the function has no
30// more work to do and that the thread can be released.
31typedef bool(*ThreadRunFunction)(ThreadObj);
32
33enum ThreadPriority {
34  kLowPriority = 1,
35  kNormalPriority = 2,
36  kHighPriority = 3,
37  kHighestPriority = 4,
38  kRealtimePriority = 5
39};
40
41class ThreadWrapper {
42 public:
43  enum {kThreadMaxNameLength = 64};
44
45  virtual ~ThreadWrapper() {};
46
47  // Factory method. Constructor disabled.
48  //
49  // func        Pointer to a, by user, specified callback function.
50  // obj         Object associated with the thread. Passed in the callback
51  //             function.
52  // prio        Thread priority. May require root/admin rights.
53  // thread_name  NULL terminated thread name, will be visable in the Windows
54  //             debugger.
55  static ThreadWrapper* CreateThread(ThreadRunFunction func,
56                                     ThreadObj obj,
57                                     ThreadPriority prio = kNormalPriority,
58                                     const char* thread_name = 0);
59
60  // Get the current thread's kernel thread ID.
61  static uint32_t GetThreadId();
62
63  // Non blocking termination of the spawned thread. Note that it is not safe
64  // to delete this class until the spawned thread has been reclaimed.
65  virtual void SetNotAlive() = 0;
66
67  // Tries to spawns a thread and returns true if that was successful.
68  // Additionally, it tries to set thread priority according to the priority
69  // from when CreateThread was called. However, failure to set priority will
70  // not result in a false return value.
71  // TODO(henrike): add a function for polling whether priority was set or
72  //                not.
73  virtual bool Start(unsigned int& id) = 0;
74
75  // Sets the threads CPU affinity. CPUs are listed 0 - (number of CPUs - 1).
76  // The numbers in processor_numbers specify which CPUs are allowed to run the
77  // thread. processor_numbers should not contain any duplicates and elements
78  // should be lower than (number of CPUs - 1). amount_of_processors should be
79  // equal to the number of processors listed in processor_numbers.
80  virtual bool SetAffinity(const int* processor_numbers,
81                           const unsigned int amount_of_processors);
82
83  // Stops the spawned thread and waits for it to be reclaimed with a timeout
84  // of two seconds. Will return false if the thread was not reclaimed.
85  // Multiple tries to Stop are allowed (e.g. to wait longer than 2 seconds).
86  // It's ok to call Stop() even if the spawned thread has been reclaimed.
87  virtual bool Stop() = 0;
88};
89
90}  // namespace webrtc
91
92#endif  // WEBRTC_SYSTEM_WRAPPERS_INTERFACE_THREAD_WRAPPER_H_
93