Extract Awakable from Waiter

mojo/edk/system/awakable.h

+// Copyright 2013 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef MOJO_EDK_SYSTEM_AWAKABLE_H_
+#define MOJO_EDK_SYSTEM_AWAKABLE_H_
+
+#include <stdint.h>
+
+#include "mojo/public/c/system/types.h"
+
+namespace mojo {
+namespace system {
+
+// Awakable is a callback that is called by AwakableList.

[viettrungluu, 2014/12/03 21:18:13]

nit: For consistency with the rest of the directory, enclose "code" in between
|...|: e.g., "|Awakable|" and "|AwakableList|".

Also, "callback" isn't quite right. I'd say: "|Awakable| is an interface for
things that may be waited on (from some separate thread).".

[Hajime Morrita, 2014/12/03 21:44:09]

Done.

+// The Awake() callback must satisfy following contract:

[viettrungluu, 2014/12/03 21:18:13]

Put this comment above |Awake()|. You can rewrite it to say: "|Awake()| must
satisfy the following contract:".

[Hajime Morrita, 2014/12/03 21:44:09]

Done.

+//
+// * As it is called from any thread, the callback must be thread-safe.

[viettrungluu, 2014/12/03 21:18:13]

"it" -> "this", "the callback" -> "this"

[Hajime Morrita, 2014/12/03 21:44:09]

Done.

+// * As it is called inside a lock, the callback must not call API that

[viettrungluu, 2014/12/03 21:18:13]

"it" -> "this", "the callback" -> "this"

More significantly, this is not right. say '... this must not call anything that
takes "non-terminal" locks, i.e., those which are always safe to take.'.

(E.g., |Waiter|'s lock is safe to take. E.g., if one has a refcounted class
whose refcount is protected by a lock -- which protects nothing else -- taking
it would also be safe.)

[Hajime Morrita, 2014/12/03 21:44:09]

That is right. "any lock" is unnecessarily restrictive.

+//   does lock any Mojo-related objects.
+class Awakable {
+ public:
+  virtual void Awake(MojoResult result, uintptr_t context) = 0;
+};
+
+}  // namespace system
+}  // namespace mojo
+
+#endif  // MOJO_EDK_SYSTEM_AWAKABLE_H_