message_port_descriptor.h | Explore in Territory

// Copyright 2019 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef THIRD_PARTY_BLINK_PUBLIC_COMMON_MESSAGING_MESSAGE_PORT_DESCRIPTOR_H_
#define THIRD_PARTY_BLINK_PUBLIC_COMMON_MESSAGING_MESSAGE_PORT_DESCRIPTOR_H_

#include "base/dcheck_is_on.h"
#include "base/unguessable_token.h"
#include "mojo/public/cpp/system/message_pipe.h"
#include "third_party/blink/public/common/common_export.h"

namespace blink {

class ExecutionContext;

// Defines a message port descriptor, which is a mojo::MessagePipeHandle and
// some associated state which follows the handle around as it is passed from
// one execution context to another. This can be serialized into a
// mojom::MessagePortDescriptor using MessagePortDescriptorStructTraits. Since
// this class uses only POD and Mojo types the same serialization logic is fine
// for use both inside and outside of Blink. This type is move-only so that only
// a single representation of an endpoint can exist at any moment in time.
// This class is not thread-safe, but a MessagePortDescriptor is only ever owned
// by a single thread at a time.
//
// A MessagePortDescriptor should never be created in isolation, but rather they
// should only be created in pairs via MessagePortDescriptorPair.
//
// To enforce that a Mojo pipe isn't left dangling, MessagePortDescriptors
// enforce that they are only destroyed while holding onto their pipe.
//
// This class is intended to be used as follows:
//
//   MessagePortDescriptorPair port_pair;
//   MessagePortDescriptor port0 = port_pair.TakePort0();
//   MessagePortDescriptor port1 = port_pair.TakePort1();
//
//   ... pass around the port descriptors in TransferableMessages as desired ...
//
//   // Pass this into a MessagePortChannel for reference-counted safe-keeping.
//   MessagePortChannel channel0(port0);
//
//   // Entangle into a MessagePort for use in sending messages.
//   MessagePort message_port;
//   message_port.Entangle(channel0)
//   message_port.postMessage(...);
//   channel0 = message_port.Disentangle();
//
// Note that there is a Java wrapper to this class implemented by
// org.chromium.content.browser.AppWebMessagePortDescriptor.
class BLINK_COMMON_EXPORT MessagePortDescriptor { … };

// Defines a wrapped mojo::MessagePipe, containing 2 MessagePortDescriptors that
// are peers of each other.
class BLINK_COMMON_EXPORT MessagePortDescriptorPair { … };

// A delegate used for instrumenting operations on message handle descriptors.
// These messages allow the observing entity to follow the handle endpoints as
// they travel from one execution context to another, and to know when they are
// bound. If no instrumentation delegate is provided the instrumentation is
// disabled. The implementation needs to be thread-safe.
//
// Note that the sequence numbers associated with each port will never be
// reused, and increment by exactly one for each message received. This allows
// the receiver to order incoming messages and know if a message is missing.
// NotifyMessagePortsCreated is special in that it introduces new ports and
// starts new sequence numbers. The next message received (either a PortAttached
// or PortDestroyed message) will use the subsequent sequence number.
class BLINK_COMMON_EXPORT MessagePortDescriptor::InstrumentationDelegate { … };

}  // namespace blink

#endif  // THIRD_PARTY_BLINK_PUBLIC_COMMON_MESSAGING_MESSAGE_PORT_DESCRIPTOR_H_
chromium/third_party/blink/public/common/messaging/message_port_descriptor.h
