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