Allow mojo::system::RawChannel::Delegate methods to destroy the RawChannel.

mojo/edk/system/raw_channel.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_RAW_CHANNEL_H_
 #define MOJO_EDK_SYSTEM_RAW_CHANNEL_H_
 
 #include <deque>
 #include <vector>
 
@@ skipping 23 matching lines @@
 //    the aforementioned thread).
 //
 // OS-specific implementation subclasses are to be instantiated using the
 // |Create()| static factory method.
 //
 // With the exception of |WriteMessage()|, this class is thread-unsafe (and in
 // general its methods should only be used on the I/O thread, i.e., the thread
 // on which |Init()| is called).
 class MOJO_SYSTEM_IMPL_EXPORT RawChannel {
  public:
+  // This object may be destroyed on any thread (if |Init()| was called, after
+  // |Shutdown()| was called).
   virtual ~RawChannel();
 
   // The |Delegate| is only accessed on the same thread as the message loop
   // (passed in on creation).
   class MOJO_SYSTEM_IMPL_EXPORT Delegate {
    public:
     enum Error {
       // Failed read due to raw channel shutdown (e.g., on the other side).
       ERROR_READ_SHUTDOWN,
       // Failed read due to raw channel being broken (e.g., if the other side
       // died without shutting down).
       ERROR_READ_BROKEN,
       // Received a bad message.
       ERROR_READ_BAD_MESSAGE,
       // Unknown read error.
       ERROR_READ_UNKNOWN,
       // Generic write error.
       ERROR_WRITE
     };
 
-    // Called when a message is read. This may call |Shutdown()| (on the
-    // |RawChannel|), but must not destroy it.
+    // Called when a message is read. This may call the |RawChannel|'s
+    // |Shutdown()| and then (if desired) destroy it.
     virtual void OnReadMessage(
         const MessageInTransit::View& message_view,
         embedder::ScopedPlatformHandleVectorPtr platform_handles) = 0;
 
-    // Called when there's a (fatal) error. This may call the raw channel's
-    // |Shutdown()|, but must not destroy it.
+    // Called when there's a (fatal) error. This may call the |RawChannel|'s
+    // |Shutdown()| and then (if desired) destroy it.
     //
     // For each raw channel, there'll be at most one |ERROR_READ_...| and at
     // most one |ERROR_WRITE| notification. After |OnError(ERROR_READ_...)|,
     // |OnReadMessage()| won't be called again.
     virtual void OnError(Error error) = 0;
 
    protected:
     virtual ~Delegate() {}
   };
 
@@ skipping 108 matching lines @@
     // indicates the position in the first message's data to start the next
     // write.
     size_t data_offset_;
 
     DISALLOW_COPY_AND_ASSIGN(WriteBuffer);
   };
 
   RawChannel();
 
   // |result| must not be |IO_PENDING|. Must be called on the I/O thread WITHOUT
-  // |write_lock_| held.
+  // |write_lock_| held. This object may be destroyed by this call.
   void OnReadCompleted(IOResult io_result, size_t bytes_read);
   // |result| must not be |IO_PENDING|. Must be called on the I/O thread WITHOUT
-  // |write_lock_| held.
+  // |write_lock_| held. This object may be destroyed by this call.
   void OnWriteCompleted(IOResult io_result,
                         size_t platform_handles_written,
                         size_t bytes_written);
 
   base::MessageLoopForIO* message_loop_for_io() { return message_loop_for_io_; }
   base::Lock& write_lock() { return write_lock_; }
 
   // Should only be called on the I/O thread.
   ReadBuffer* read_buffer() { return read_buffer_.get(); }
 
@@ skipping 59 matching lines @@
   virtual IOResult WriteNoLock(size_t* platform_handles_written,
                                size_t* bytes_written) = 0;
   // Similar to |WriteNoLock()|, except that the implementing subclass must also
   // guarantee that the method doesn't succeed synchronously, i.e., it only
   // returns |IO_FAILED_...| or |IO_PENDING|.
   virtual IOResult ScheduleWriteNoLock() = 0;
 
   // Must be called on the I/O thread WITHOUT |write_lock_| held.
   virtual void OnInit() = 0;
   // On shutdown, passes the ownership of the buffers to subclasses, which may
-  // want to preserve them if there are pending read/write. Must be called on
-  // the I/O thread under |write_lock_|.
+  // want to preserve them if there are pending read/writes. After this is
+  // called, |OnReadCompleted()| must no longer be called. Must be called on the
+  // I/O thread under |write_lock_|.
   virtual void OnShutdownNoLock(scoped_ptr<ReadBuffer> read_buffer,
                                 scoped_ptr<WriteBuffer> write_buffer) = 0;
 
  private:
   // Converts an |IO_FAILED_...| for a read to a |Delegate::Error|.
   static Delegate::Error ReadIOResultToError(IOResult io_result);
 
   // Calls |delegate_->OnError(error)|. Must be called on the I/O thread WITHOUT
-  // |write_lock_| held.
+  // |write_lock_| held. This object may be destroyed by this call.
   void CallOnError(Delegate::Error error);
 
   // If |io_result| is |IO_SUCCESS|, updates the write buffer and schedules a
   // write operation to run later if there is more to write. If |io_result| is
   // failure or any other error occurs, cancels pending writes and returns
   // false. Must be called under |write_lock_| and only if |write_stopped_| is
   // false.
   bool OnWriteCompletedNoLock(IOResult io_result,
                               size_t platform_handles_written,
                               size_t bytes_written);
 
   // Set in |Init()| and never changed (hence usable on any thread without
   // locking):
   base::MessageLoopForIO* message_loop_for_io_;
 
   // Only used on the I/O thread:
   Delegate* delegate_;
-  bool read_stopped_;
+  bool* set_on_shutdown_;
   scoped_ptr<ReadBuffer> read_buffer_;
 
   base::Lock write_lock_;  // Protects the following members.
   bool write_stopped_;
   scoped_ptr<WriteBuffer> write_buffer_;
 
   // This is used for posting tasks from write threads to the I/O thread. It
   // must only be accessed under |write_lock_|. The weak pointers it produces
   // are only used/invalidated on the I/O thread.
   base::WeakPtrFactory<RawChannel> weak_ptr_factory_;
 
   DISALLOW_COPY_AND_ASSIGN(RawChannel);
 };
 
 }  // namespace system
 }  // namespace mojo
 
 #endif  // MOJO_EDK_SYSTEM_RAW_CHANNEL_H_