1 // Copyright 2013 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 #ifndef MOJO_SYSTEM_DISPATCHER_H_ 6 #define MOJO_SYSTEM_DISPATCHER_H_ 7 8 #include <vector> 9 10 #include "base/basictypes.h" 11 #include "base/memory/ref_counted.h" 12 #include "base/synchronization/lock.h" 13 #include "mojo/public/system/core.h" 14 #include "mojo/system/system_impl_export.h" 15 16 namespace mojo { 17 namespace system { 18 19 class CoreImpl; 20 class Waiter; 21 22 // A |Dispatcher| implements Mojo primitives that are "attached" to a particular 23 // handle. This includes most (all?) primitives except for |MojoWait...()|. This 24 // object is thread-safe, with its state being protected by a single lock 25 // |lock_|, which is also made available to implementation subclasses (via the 26 // |lock()| method). 27 class MOJO_SYSTEM_IMPL_EXPORT Dispatcher : 28 public base::RefCountedThreadSafe<Dispatcher> { 29 public: 30 // These methods implement the various primitives named |Mojo...()|. These 31 // take |lock_| and handle races with |Close()|. Then they call out to 32 // subclasses' |...ImplNoLock()| methods (still under |lock_|), which actually 33 // implement the primitives. 34 // NOTE(vtl): This puts a big lock around each dispatcher (i.e., handle), and 35 // prevents the various |...ImplNoLock()|s from releasing the lock as soon as 36 // possible. If this becomes an issue, we can rethink this. 37 MojoResult Close(); 38 // |dispatchers| may be non-null if and only if there are handles to be 39 // written, in which case this will be called with all the dispatchers' locks 40 // held. On success, all the dispatchers must have been moved to a closed 41 // state; on failure, they should remain in their original state. 42 MojoResult WriteMessage(const void* bytes, 43 uint32_t num_bytes, 44 const std::vector<Dispatcher*>* dispatchers, 45 MojoWriteMessageFlags flags); 46 // |dispatchers| must be non-null but empty, if |num_dispatchers| is non-null 47 // and nonzero. On success, it will be set to the dispatchers to be received 48 // (and assigned handles) as part of the message. 49 MojoResult ReadMessage( 50 void* bytes, 51 uint32_t* num_bytes, 52 std::vector<scoped_refptr<Dispatcher> >* dispatchers, 53 uint32_t* num_dispatchers, 54 MojoReadMessageFlags flags); 55 MojoResult WriteData(const void* elements, 56 uint32_t* num_elements, 57 MojoWriteDataFlags flags); 58 MojoResult BeginWriteData(void** buffer, 59 uint32_t* buffer_num_elements, 60 MojoWriteDataFlags flags); 61 MojoResult EndWriteData(uint32_t num_elements_written); 62 MojoResult ReadData(void* elements, 63 uint32_t* num_elements, 64 MojoReadDataFlags flags); 65 MojoResult BeginReadData(const void** buffer, 66 uint32_t* buffer_num_elements, 67 MojoReadDataFlags flags); 68 MojoResult EndReadData(uint32_t num_elements_read); 69 70 // Adds a waiter to this dispatcher. The waiter will be woken up when this 71 // object changes state to satisfy |flags| with result |wake_result| (which 72 // must be >= 0, i.e., a success status). It will also be woken up when it 73 // becomes impossible for the object to ever satisfy |flags| with a suitable 74 // error status. 75 // 76 // Returns: 77 // - |MOJO_RESULT_OK| if the waiter was added; 78 // - |MOJO_RESULT_ALREADY_EXISTS| if |flags| is already satisfied; 79 // - |MOJO_RESULT_INVALID_ARGUMENT| if the dispatcher has been closed; and 80 // - |MOJO_RESULT_FAILED_PRECONDITION| if it is not (or no longer) possible 81 // that |flags| will ever be satisfied. 82 MojoResult AddWaiter(Waiter* waiter, 83 MojoWaitFlags flags, 84 MojoResult wake_result); 85 void RemoveWaiter(Waiter* waiter); 86 87 // Creates an equivalent dispatcher -- representing the same resource as this 88 // dispatcher -- and close (i.e., disable) this dispatcher. I.e., this 89 // dispatcher will look as though it was closed, but the resource it 90 // represents will be assigned to the new dispatcher. This must be called 91 // under the dispatcher's lock. 92 scoped_refptr<Dispatcher> CreateEquivalentDispatcherAndCloseNoLock(); 93 94 protected: 95 Dispatcher(); 96 97 friend class base::RefCountedThreadSafe<Dispatcher>; 98 virtual ~Dispatcher(); 99 100 // These are to be overridden by subclasses (if necessary). They are called 101 // exactly once -- first |CancelAllWaitersNoLock()|, then |CloseImplNoLock()|, 102 // when the dispatcher is being closed. They are called under |lock_|. 103 virtual void CancelAllWaitersNoLock(); 104 virtual MojoResult CloseImplNoLock(); 105 106 // These are to be overridden by subclasses (if necessary). They are never 107 // called after the dispatcher has been closed. They are called under |lock_|. 108 // See the descriptions of the methods without the "ImplNoLock" for more 109 // information. 110 virtual MojoResult WriteMessageImplNoLock( 111 const void* bytes, 112 uint32_t num_bytes, 113 const std::vector<Dispatcher*>* dispatchers, 114 MojoWriteMessageFlags flags); 115 virtual MojoResult ReadMessageImplNoLock( 116 void* bytes, 117 uint32_t* num_bytes, 118 std::vector<scoped_refptr<Dispatcher> >* dispatchers, 119 uint32_t* num_dispatchers, 120 MojoReadMessageFlags flags); 121 virtual MojoResult WriteDataImplNoLock(const void* elements, 122 uint32_t* num_elements, 123 MojoWriteDataFlags flags); 124 virtual MojoResult BeginWriteDataImplNoLock(void** buffer, 125 uint32_t* buffer_num_elements, 126 MojoWriteDataFlags flags); 127 virtual MojoResult EndWriteDataImplNoLock(uint32_t num_elements_written); 128 virtual MojoResult ReadDataImplNoLock(void* elements, 129 uint32_t* num_elements, 130 MojoReadDataFlags flags); 131 virtual MojoResult BeginReadDataImplNoLock(const void** buffer, 132 uint32_t* buffer_num_elements, 133 MojoReadDataFlags flags); 134 virtual MojoResult EndReadDataImplNoLock(uint32_t num_elements_read); 135 virtual MojoResult AddWaiterImplNoLock(Waiter* waiter, 136 MojoWaitFlags flags, 137 MojoResult wake_result); 138 virtual void RemoveWaiterImplNoLock(Waiter* waiter); 139 140 // This must be implemented by subclasses, since only they can instantiate a 141 // new dispatcher of the same class. See 142 // |CreateEquivalentDispatcherAndCloseNoLock()| for more details. 143 virtual scoped_refptr<Dispatcher> 144 CreateEquivalentDispatcherAndCloseImplNoLock() = 0; 145 146 // Available to subclasses. (Note: Returns a non-const reference, just like 147 // |base::AutoLock|'s constructor takes a non-const reference.) 148 base::Lock& lock() const { return lock_; } 149 150 bool is_closed_no_lock() const { return is_closed_; } 151 152 private: 153 // For |WriteMessage()|, |CoreImpl| needs access to |lock()| and 154 // |is_closed_no_lock()|. 155 friend class CoreImpl; 156 157 // This protects the following members as well as any state added by 158 // subclasses. 159 mutable base::Lock lock_; 160 bool is_closed_; 161 162 DISALLOW_COPY_AND_ASSIGN(Dispatcher); 163 }; 164 165 } // namespace system 166 } // namespace mojo 167 168 #endif // MOJO_SYSTEM_DISPATCHER_H_ 169
