platform_thread.h revision ddb351dbec246cf1fab5ec20d2d5520909041de1 
1// Copyright (c) 2011 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// WARNING: You should *NOT* be using this class directly.  PlatformThread is
6// the low-level platform-specific abstraction to the OS's threading interface.
7// You should instead be using a message-loop driven Thread, see thread.h.
8
9#ifndef BASE_THREADING_PLATFORM_THREAD_H_
10#define BASE_THREADING_PLATFORM_THREAD_H_
11#pragma once
12
13#include "base/base_api.h"
14#include "base/basictypes.h"
15#include "build/build_config.h"
16
17#if defined(OS_WIN)
18#include <windows.h>
19#elif defined(OS_POSIX)
20#include <pthread.h>
21#if defined(OS_MACOSX)
22#include <mach/mach.h>
23#else  // OS_POSIX && !OS_MACOSX
24#include <unistd.h>
25#endif
26#endif
27
28namespace base {
29
30// PlatformThreadHandle should not be assumed to be a numeric type, since the
31// standard intends to allow pthread_t to be a structure.  This means you
32// should not initialize it to a value, like 0.  If it's a member variable, the
33// constructor can safely "value initialize" using () in the initializer list.
34#if defined(OS_WIN)
35typedef DWORD PlatformThreadId;
36typedef void* PlatformThreadHandle;  // HANDLE
37const PlatformThreadHandle kNullThreadHandle = NULL;
38#elif defined(OS_POSIX)
39typedef pthread_t PlatformThreadHandle;
40const PlatformThreadHandle kNullThreadHandle = 0;
41#if defined(OS_MACOSX)
42typedef mach_port_t PlatformThreadId;
43#else  // OS_POSIX && !OS_MACOSX
44typedef pid_t PlatformThreadId;
45#endif
46#endif
47
48const PlatformThreadId kInvalidThreadId = 0;
49
50// A namespace for low-level thread functions.
51class BASE_API PlatformThread {
52 public:
53  // Implement this interface to run code on a background thread.  Your
54  // ThreadMain method will be called on the newly created thread.
55  class BASE_API Delegate {
56   public:
57    virtual ~Delegate() {}
58    virtual void ThreadMain() = 0;
59  };
60
61  // Gets the current thread id, which may be useful for logging purposes.
62  static PlatformThreadId CurrentId();
63
64  // Yield the current thread so another thread can be scheduled.
65  static void YieldCurrentThread();
66
67  // Sleeps for the specified duration (units are milliseconds).
68  static void Sleep(int duration_ms);
69
70  // Sets the thread name visible to a debugger.  This has no effect otherwise.
71  static void SetName(const char* name);
72
73  // Creates a new thread.  The |stack_size| parameter can be 0 to indicate
74  // that the default stack size should be used.  Upon success,
75  // |*thread_handle| will be assigned a handle to the newly created thread,
76  // and |delegate|'s ThreadMain method will be executed on the newly created
77  // thread.
78  // NOTE: When you are done with the thread handle, you must call Join to
79  // release system resources associated with the thread.  You must ensure that
80  // the Delegate object outlives the thread.
81  static bool Create(size_t stack_size, Delegate* delegate,
82                     PlatformThreadHandle* thread_handle);
83
84  // CreateNonJoinable() does the same thing as Create() except the thread
85  // cannot be Join()'d.  Therefore, it also does not output a
86  // PlatformThreadHandle.
87  static bool CreateNonJoinable(size_t stack_size, Delegate* delegate);
88
89  // Joins with a thread created via the Create function.  This function blocks
90  // the caller until the designated thread exits.  This will invalidate
91  // |thread_handle|.
92  static void Join(PlatformThreadHandle thread_handle);
93
94 private:
95  DISALLOW_IMPLICIT_CONSTRUCTORS(PlatformThread);
96};
97
98}  // namespace base
99
100#endif  // BASE_THREADING_PLATFORM_THREAD_H_
101