mojo/system/handle_table.h

   1 // Copyright 2014 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_HANDLE_TABLE_H_
   6 #define MOJO_SYSTEM_HANDLE_TABLE_H_
   7
   8 #include <utility>
   9 #include <vector>
  10
  11 #include "base/containers/hash_tables.h"
  12 #include "base/macros.h"
  13 #include "base/memory/ref_counted.h"
  14 #include "mojo/public/c/system/types.h"
  15 #include "mojo/system/system_impl_export.h"
  16
  17 namespace mojo {
  18 namespace system {
  19
  20 class Core;
  21 class Dispatcher;
  22 class DispatcherTransport;
  23
  24 typedef std::vector<scoped_refptr<Dispatcher> > DispatcherVector;
  25
  26 // Test-only function (defined/used in embedder/test_embedder.cc). Declared here
  27 // so it can be friended.
  28 namespace internal {
  29 bool ShutdownCheckNoLeaks(Core*);
  30 }
  31
  32 // This class provides the (global) handle table (owned by |Core|), which maps
  33 // (valid) |MojoHandle|s to |Dispatcher|s. This is abstracted so that, e.g.,
  34 // caching may be added.
  35 //
  36 // This class is NOT thread-safe; locking is left to |Core| (since it may need
  37 // to make several changes -- "atomically" or in rapid successsion, in which
  38 // case the extra locking/unlocking would be unnecessary overhead).
  39
  40 class MOJO_SYSTEM_IMPL_EXPORT HandleTable {
  41  public:
  42   HandleTable();
  43   ~HandleTable();
  44
  45   // Gets the dispatcher for a given handle (which should not be
  46   // |MOJO_HANDLE_INVALID|). Returns null if there's no dispatcher for the given
  47   // handle.
  48   // WARNING: For efficiency, this returns a dumb pointer. If you're going to
  49   // use the result outside |Core|'s lock, you MUST take a reference (e.g., by
  50   // storing the result inside a |scoped_refptr|).
  51   Dispatcher* GetDispatcher(MojoHandle handle);
  52
  53   // On success, gets the dispatcher for a given handle (which should not be
  54   // |MOJO_HANDLE_INVALID|) and removes it. (On failure, returns an appropriate
  55   // result (and leaves |dispatcher| alone), namely
  56   // |MOJO_RESULT_INVALID_ARGUMENT| if there's no dispatcher for the given
  57   // handle or |MOJO_RESULT_BUSY| if the handle is marked as busy.)
  58   MojoResult GetAndRemoveDispatcher(MojoHandle handle,
  59                                     scoped_refptr<Dispatcher>* dispatcher);
  60
  61   // Adds a dispatcher (which must be valid), returning the handle for it.
  62   // Returns |MOJO_HANDLE_INVALID| on failure (if the handle table is full).
  63   MojoHandle AddDispatcher(const scoped_refptr<Dispatcher>& dispatcher);
  64
  65   // Adds a pair of dispatchers (which must be valid), return a pair of handles
  66   // for them. On failure (if the handle table is full), the first (and second)
  67   // handles will be |MOJO_HANDLE_INVALID|, and neither dispatcher will be
  68   // added.
  69   std::pair<MojoHandle, MojoHandle> AddDispatcherPair(
  70       const scoped_refptr<Dispatcher>& dispatcher0,
  71       const scoped_refptr<Dispatcher>& dispatcher1);
  72
  73   // Adds the given vector of dispatchers (of size at most
  74   // |kMaxMessageNumHandles|). |handles| must point to an array of size at least
  75   // |dispatchers.size()|. Unlike the other |AddDispatcher...()| functions, some
  76   // of the dispatchers may be invalid (null). Returns true on success and false
  77   // on failure (if the handle table is full), in which case it leaves
  78   // |handles[...]| untouched (and all dispatchers unadded).
  79   bool AddDispatcherVector(const DispatcherVector& dispatchers,
  80                            MojoHandle* handles);
  81
  82   // Tries to mark the given handles as busy and start transport on them (i.e.,
  83   // take their dispatcher locks); |transports| must be sized to contain
  84   // |num_handles| elements. On failure, returns them to their original
  85   // (non-busy, unlocked state).
  86   MojoResult MarkBusyAndStartTransport(
  87       MojoHandle disallowed_handle,
  88       const MojoHandle* handles,
  89       uint32_t num_handles,
  90       std::vector<DispatcherTransport>* transports);
  91
  92   // Remove the given handles, which must all be present and which should have
  93   // previously been marked busy by |MarkBusyAndStartTransport()|.
  94   void RemoveBusyHandles(const MojoHandle* handles, uint32_t num_handles);
  95
  96   // Restores the given handles, which must all be present and which should have
  97   // previously been marked busy by |MarkBusyAndStartTransport()|, to a non-busy
  98   // state.
  99   void RestoreBusyHandles(const MojoHandle* handles, uint32_t num_handles);
 100
 101  private:
 102   friend bool internal::ShutdownCheckNoLeaks(Core*);
 103
 104   // The |busy| member is used only to deal with functions (in particular
 105   // |Core::WriteMessage()|) that want to hold on to a dispatcher and later
 106   // remove it from the handle table, without holding on to the handle table
 107   // lock.
 108   //
 109   // For example, if |Core::WriteMessage()| is called with a handle to be sent,
 110   // (under the handle table lock) it must first check that that handle is not
 111   // busy (if it is busy, then it fails with |MOJO_RESULT_BUSY|) and then marks
 112   // it as busy. To avoid deadlock, it should also try to acquire the locks for
 113   // all the dispatchers for the handles that it is sending (and fail with
 114   // |MOJO_RESULT_BUSY| if the attempt fails). At this point, it can release the
 115   // handle table lock.
 116   //
 117   // If |Core::Close()| is simultaneously called on that handle, it too checks
 118   // if the handle is marked busy. If it is, it fails (with |MOJO_RESULT_BUSY|).
 119   // This prevents |Core::WriteMessage()| from sending a handle that has been
 120   // closed (or learning about this too late).
 121   struct Entry {
 122     Entry();
 123     explicit Entry(const scoped_refptr<Dispatcher>& dispatcher);
 124     ~Entry();
 125
 126     scoped_refptr<Dispatcher> dispatcher;
 127     bool busy;
 128   };
 129   typedef base::hash_map<MojoHandle, Entry> HandleToEntryMap;
 130
 131   // Adds the given dispatcher to the handle table, not doing any size checks.
 132   MojoHandle AddDispatcherNoSizeCheck(
 133       const scoped_refptr<Dispatcher>& dispatcher);
 134
 135   HandleToEntryMap handle_to_entry_map_;
 136   MojoHandle next_handle_;  // Invariant: never |MOJO_HANDLE_INVALID|.
 137
 138   DISALLOW_COPY_AND_ASSIGN(HandleTable);
 139 };
 140
 141 }  // namespace system
 142 }  // namespace mojo
 143
 144 #endif  // MOJO_SYSTEM_HANDLE_TABLE_H_