Updating trunk VERSION from 935.0 to 936.0
[chromium-blink-merge.git] / base / message_loop_proxy.h
blobd783b4e6bc7c61142a7a2458948441696103138b
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.
5 #ifndef BASE_MESSAGE_LOOP_PROXY_H_
6 #define BASE_MESSAGE_LOOP_PROXY_H_
7 #pragma once
9 #include "base/base_export.h"
10 #include "base/basictypes.h"
11 #include "base/callback.h"
12 #include "base/memory/ref_counted.h"
13 #include "base/task.h"
15 namespace tracked_objects {
16 class Location;
17 } // namespace tracked_objects
19 namespace base {
21 struct MessageLoopProxyTraits;
23 // This class provides a thread-safe refcounted interface to the Post* methods
24 // of a message loop. This class can outlive the target message loop.
25 // MessageLoopProxy objects are constructed automatically for all MessageLoops.
26 // So, to access them, you can use any of the following:
27 // Thread::message_loop_proxy()
28 // MessageLoop::current()->message_loop_proxy()
29 // MessageLoopProxy::current()
30 class BASE_EXPORT MessageLoopProxy
31 : public base::RefCountedThreadSafe<MessageLoopProxy,
32 MessageLoopProxyTraits> {
33 public:
34 // These methods are the same as in message_loop.h, but are guaranteed to
35 // either post the Task to the MessageLoop (if it's still alive), or to
36 // delete the Task otherwise.
37 // They return true iff the thread existed and the task was posted. Note that
38 // even if the task is posted, there's no guarantee that it will run; for
39 // example the target loop may already be quitting, or in the case of a
40 // delayed task a Quit message may preempt it in the message loop queue.
41 // Conversely, a return value of false is a guarantee the task will not run.
42 virtual bool PostTask(const tracked_objects::Location& from_here,
43 Task* task) = 0;
44 virtual bool PostDelayedTask(const tracked_objects::Location& from_here,
45 Task* task,
46 int64 delay_ms) = 0;
47 virtual bool PostNonNestableTask(const tracked_objects::Location& from_here,
48 Task* task) = 0;
49 virtual bool PostNonNestableDelayedTask(
50 const tracked_objects::Location& from_here,
51 Task* task,
52 int64 delay_ms) = 0;
54 // TODO(ajwong): Remove the functions above once the Task -> Closure migration
55 // is complete.
57 // There are 2 sets of Post*Task functions, one which takes the older Task*
58 // function object representation, and one that takes the newer base::Closure.
59 // We have this overload to allow a staged transition between the two systems.
60 // Once the transition is done, the functions above should be deleted.
61 virtual bool PostTask(const tracked_objects::Location& from_here,
62 const base::Closure& task) = 0;
63 virtual bool PostDelayedTask(const tracked_objects::Location& from_here,
64 const base::Closure& task,
65 int64 delay_ms) = 0;
66 virtual bool PostNonNestableTask(const tracked_objects::Location& from_here,
67 const base::Closure& task) = 0;
68 virtual bool PostNonNestableDelayedTask(
69 const tracked_objects::Location& from_here,
70 const base::Closure& task,
71 int64 delay_ms) = 0;
73 // A method which checks if the caller is currently running in the thread that
74 // this proxy represents.
75 virtual bool BelongsToCurrentThread() = 0;
77 // Executes |task| on the given MessageLoopProxy. On completion, |reply|
78 // is passed back to the MessageLoopProxy for the thread that called
79 // PostTaskAndReply(). Both |task| and |reply| are guaranteed to be deleted
80 // on the thread from which PostTaskAndReply() is invoked. This allows
81 // objects that must be deleted on the originating thread to be bound into the
82 // |task| and |reply| Closures. In particular, it can be useful to use
83 // WeakPtr<> in the |reply| Closure so that the reply operation can be
84 // canceled. See the following pseudo-code:
86 // class DataBuffer : public RefCountedThreadSafe<DataBuffer> {
87 // public:
88 // // Called to add data into a buffer.
89 // void AddData(void* buf, size_t length);
90 // ...
91 // };
94 // class DataLoader : public SupportsWeakPtr<DataLoader> {
95 // public:
96 // void GetData() {
97 // scoped_refptr<DataBuffer> buffer = new DataBuffer();
98 // target_thread_.message_loop_proxy()->PostTaskAndReply(
99 // FROM_HERE,
100 // base::Bind(&DataBuffer::AddData, buffer),
101 // base::Bind(&DataLoader::OnDataReceived, AsWeakPtr(), buffer));
102 // }
104 // private:
105 // void OnDataReceived(scoped_refptr<DataBuffer> buffer) {
106 // // Do something with buffer.
107 // }
108 // };
111 // Things to notice:
112 // * Results of |task| are shared with |reply| by binding a shared argument
113 // (a DataBuffer instance).
114 // * The DataLoader object has no special thread safety.
115 // * The DataLoader object can be deleted while |task| is still running,
116 // and the reply will cancel itself safely because it is bound to a
117 // WeakPtr<>.
118 bool PostTaskAndReply(const tracked_objects::Location& from_here,
119 const Closure& task,
120 const Closure& reply);
122 template <class T>
123 bool DeleteSoon(const tracked_objects::Location& from_here,
124 T* object) {
125 return PostNonNestableTask(from_here, new DeleteTask<T>(object));
127 template <class T>
128 bool ReleaseSoon(const tracked_objects::Location& from_here,
129 T* object) {
130 return PostNonNestableTask(from_here, new ReleaseTask<T>(object));
133 // Gets the MessageLoopProxy for the current message loop, creating one if
134 // needed.
135 static scoped_refptr<MessageLoopProxy> current();
137 protected:
138 friend class RefCountedThreadSafe<MessageLoopProxy, MessageLoopProxyTraits>;
139 friend struct MessageLoopProxyTraits;
141 MessageLoopProxy();
142 virtual ~MessageLoopProxy();
144 // Called when the proxy is about to be deleted. Subclasses can override this
145 // to provide deletion on specific threads.
146 virtual void OnDestruct() const;
149 struct MessageLoopProxyTraits {
150 static void Destruct(const MessageLoopProxy* proxy) {
151 proxy->OnDestruct();
155 } // namespace base
157 #endif // BASE_MESSAGE_LOOP_PROXY_H_