src/mojo/system/raw_channel.h

   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_RAW_CHANNEL_H_
   6 #define MOJO_SYSTEM_RAW_CHANNEL_H_
   7
   8 #include <vector>
   9
  10 #include "base/basictypes.h"
  11 #include "mojo/public/system/system_export.h"
  12 #include "mojo/system/limits.h"
  13
  14 namespace base {
  15 class MessageLoop;
  16 }
  17
  18 namespace mojo {
  19 namespace system {
  20
  21 class MessageInTransit;
  22
  23 // This simply wraps an |int| file descriptor on POSIX and a |HANDLE| on
  24 // Windows, but we don't want to impose, e.g., the inclusion of windows.h on
  25 // everyone.
  26 struct PlatformChannelHandle;
  27
  28 // |RawChannel| is an interface to objects that wrap an OS "pipe". It presents
  29 // the following interface to users:
  30 //  - Receives and dispatches messages on a thread (running a |MessageLoop|; it
  31 //    must be a |MessageLoopForIO| in the case of the POSIX libevent
  32 //    implementation).
  33 //  - Provides a thread-safe way of writing messages (|WriteMessage()|);
  34 //    writing/queueing messages will not block and is atomic from the point of
  35 //    view of the caller. If necessary, messages are queued (to be written on
  36 //    the aforementioned thread).
  37 //
  38 // OS-specific implementation subclasses are to be instantiated using the
  39 // |Create()| static factory method.
  40 //
  41 // With the exception of |WriteMessage()|, this class is thread-unsafe (and in
  42 // general its methods should only be used on the I/O thread).
  43 class MOJO_SYSTEM_EXPORT RawChannel {
  44  public:
  45   virtual ~RawChannel() {}
  46
  47   // The |Delegate| is only accessed on the same thread as the message loop
  48   // (passed in on creation).
  49   class Delegate {
  50    public:
  51     enum FatalError {
  52       FATAL_ERROR_UNKNOWN = 0,
  53       FATAL_ERROR_FAILED_READ,
  54       FATAL_ERROR_FAILED_WRITE
  55     };
  56
  57     // Called when a message is read. This may call |Shutdown()| on the
  58     // |RawChannel|, but must not destroy it.
  59     virtual void OnReadMessage(const MessageInTransit& message) = 0;
  60
  61     // Called when there's a fatal error, which leads to the channel no longer
  62     // being viable.
  63     virtual void OnFatalError(FatalError fatal_error) = 0;
  64
  65    protected:
  66     virtual ~Delegate() {}
  67   };
  68
  69   // Static factory method. Takes ownership of |handle| (i.e., will close it).
  70   // Does *not* take ownership of |delegate| and |message_loop|, which must
  71   // remain alive while this object does.
  72   static RawChannel* Create(const PlatformChannelHandle& handle,
  73                             Delegate* delegate,
  74                             base::MessageLoop* message_loop);
  75
  76   // This must be called (on the I/O thread) before this object is used.
  77   virtual void Init() = 0;
  78
  79   // This must be called (on the I/O thread) before this object is destroyed.
  80   virtual void Shutdown() = 0;
  81
  82   // This is thread-safe. It takes ownership of |message| (always, even on
  83   // failure). Returns true on success.
  84   virtual bool WriteMessage(MessageInTransit* message) = 0;
  85
  86  protected:
  87   RawChannel(Delegate* delegate, base::MessageLoop* message_loop)
  88       : delegate_(delegate), message_loop_(message_loop) {}
  89
  90   Delegate* delegate() { return delegate_; }
  91   base::MessageLoop* message_loop() { return message_loop_; }
  92
  93  private:
  94   Delegate* const delegate_;
  95   base::MessageLoop* const message_loop_;
  96
  97   DISALLOW_COPY_AND_ASSIGN(RawChannel);
  98 };
  99
 100 }  // namespace system
 101 }  // namespace mojo
 102
 103 #endif  // MOJO_SYSTEM_RAW_CHANNEL_H_