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
17namespace mojo {
18namespace system {
19
20class Core;
21class Dispatcher;
22class DispatcherTransport;
23
24typedef 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.
28namespace internal {
29bool 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
40class 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_
145