ray/src/plasma/format/plasma.fbs

// Plasma protocol specification

enum MessageType:int {
  // Create a new object.
  PlasmaCreateRequest = 1,
  PlasmaCreateReply,
  // Seal an object.
  PlasmaSealRequest,
  PlasmaSealReply,
  // Get an object that is stored on the local Plasma store.
  PlasmaGetRequest,
  PlasmaGetReply,
  // Release an object.
  PlasmaReleaseRequest,
  PlasmaReleaseReply,
  // Delete an object.
  PlasmaDeleteRequest,
  PlasmaDeleteReply,
  // Get status of an object.
  PlasmaStatusRequest,
  PlasmaStatusReply,
  // See if the store contains an object (will be deprecated).
  PlasmaContainsRequest,
  PlasmaContainsReply,
  // Get information for a newly connecting client.
  PlasmaConnectRequest,
  PlasmaConnectReply,
  // Make room for new objects in the plasma store.
  PlasmaEvictRequest,
  PlasmaEvictReply,
  // Fetch objects from remote Plasma stores.
  PlasmaFetchRequest,
  // Wait for objects to be ready either from local or remote Plasma stores.
  PlasmaWaitRequest,
  PlasmaWaitReply,
  // Subscribe to a list of objects or to all objects.
  PlasmaSubscribeRequest,
  // Unsubscribe.
  PlasmaUnsubscribeRequest,
  // Sending and receiving data.
  // PlasmaDataRequest initiates sending the data, there will be one
  // such message per data transfer.
  PlasmaDataRequest,
  // PlasmaDataReply contains the actual data and is sent back to the
  // object store that requested the data. For each transfer, multiple
  // reply messages get sent. Each one contains a fixed number of bytes.
  PlasmaDataReply,
  // Object notifications.
  PlasmaNotification
}

enum PlasmaError:int {
  // Operation was successful.
  OK,
  // Trying to create an object that already exists.
  ObjectExists,
  // Trying to access an object that doesn't exist.
  ObjectNonexistent,
  // Trying to create an object but there isn't enough space in the store.
  OutOfMemory
}

// Plasma store messages

struct PlasmaObjectSpec {
  // Index of the memory segment (= memory mapped file) that
  // this object is allocated in.
  segment_index: int;
  // Size in bytes of this segment (needed to call mmap).
  mmap_size: ulong;
  // The offset in bytes in the memory mapped file of the data.
  data_offset: ulong;
  // The size in bytes of the data.
  data_size: ulong;
  // The offset in bytes in the memory mapped file of the metadata.
  metadata_offset: ulong;
  // The size in bytes of the metadata.
  metadata_size: ulong;
}

table PlasmaCreateRequest {
  // ID of the object to be created.
  object_id: string;
  // The size of the object's data in bytes.
  data_size: ulong;
  // The size of the object's metadata in bytes.
  metadata_size: ulong;
}

table PlasmaCreateReply {
  // ID of the object that was created.
  object_id: string;
  // The object that is returned with this reply.
  plasma_object: PlasmaObjectSpec;
  // Error that occurred for this call.
  error: PlasmaError;
}

table PlasmaSealRequest {
  // ID of the object to be sealed.
  object_id: string;
  // Hash of the object data.
  digest: string;
}

table PlasmaSealReply {
  // ID of the object that was sealed.
  object_id: string;
  // Error code.
  error: PlasmaError;
}

table PlasmaGetRequest {
  // IDs of the objects stored at local Plasma store we are getting.
  object_ids: [string];
  // The number of milliseconds before the request should timeout.
  timeout_ms: long;
}

table PlasmaGetReply {
  // IDs of the objects being returned.
  // This number can be smaller than the number of requested
  // objects if not all requested objects are stored and sealed
  // in the local Plasma store.
  object_ids: [string];
  // Plasma object information, in the same order as their IDs.
  plasma_objects: [PlasmaObjectSpec];
  // The number of elements in both object_ids and plasma_objects arrays must agree.
}

table PlasmaReleaseRequest {
  // ID of the object to be released.
  object_id: string;
}

table PlasmaReleaseReply {
  // ID of the object that was released.
  object_id: string;
  // Error code.
  error: PlasmaError;
}

table PlasmaDeleteRequest {
  // ID of the object to be deleted.
  object_id: string;
}

table PlasmaDeleteReply {
  // ID of the object that was deleted.
  object_id: string;
  // Error code.
  error: PlasmaError;
}

table PlasmaStatusRequest {
  // IDs of the objects stored at local Plasma store we request the status of.
  object_ids: [string];
}

enum ObjectStatus:int {
  // Object is stored in the local Plasma Store.
  Local = 1,
  // Object is stored on a remote Plasma store, and it is not stored on the
  // local Plasma Store.
  Remote,
  // Object is not stored in the system.
  Nonexistent,
  // Object is currently transferred from a remote Plasma store the the local
  // Plasma Store.
  Transfer
}

table PlasmaStatusReply {
  // IDs of the objects being returned.
  object_ids: [string];
  // Status of the object.
  status: [ObjectStatus];
}

// PlasmaContains is a subset of PlasmaStatus which does not
// involve the plasma manager, only the store. We should consider
// unifying them in the future and deprecating PlasmaContains.

table PlasmaContainsRequest {
  // ID of the object we are querying.
  object_id: string;
}

table PlasmaContainsReply {
  // ID of the object we are querying.
  object_id: string;
  // 1 if the object is in the store and 0 otherwise.
  has_object: int;
}

// PlasmaConnect is used by a plasma client the first time it connects with the
// store. This is not really necessary, but is used to get some information
// about the store such as its memory capacity.

table PlasmaConnectRequest {
}

table PlasmaConnectReply {
  // The memory capacity of the store.
  memory_capacity: long;
}

table PlasmaEvictRequest {
  // Number of bytes that shall be freed.
  num_bytes: ulong;
}

table PlasmaEvictReply {
  // Number of bytes that have been freed.
  num_bytes: ulong;
}

table PlasmaFetchRequest {
  // IDs of objects to be gotten.
  object_ids: [string];
}

table ObjectRequestSpec {
  // ID of the object.
  object_id: string;
  // The type of the object. This specifies whether we
  // will be waiting for an object store in the local or
  // global Plasma store.
  type: int;
}

table PlasmaWaitRequest {
  // Array of object requests whose status we are asking for.
  object_requests: [ObjectRequestSpec];
  // Number of objects expected to be returned, if available.
  num_ready_objects: int;
  // timeout
  timeout: long;
}

table ObjectReply {
  // ID of the object.
  object_id: string;
  // The object status. This specifies where the object is stored.
  status: int;
}

table PlasmaWaitReply {
  // Array of object requests being returned.
  object_requests: [ObjectReply];
  // Number of objects expected to be returned, if available.
  num_ready_objects: int;
}

table PlasmaSubscribeRequest {
}

table PlasmaDataRequest {
  // ID of the object that is requested.
  object_id: string;
  // The host address where the data shall be sent to.
  address: string;
  // The port of the manager the data shall be sent to.
  port: int;
}

table PlasmaDataReply {
  // ID of the object that will be sent.
  object_id: string;
  // Size of the object data in bytes.
  object_size: ulong;
  // Size of the metadata in bytes.
  metadata_size: ulong;
}