1// Licensed to the Apache Software Foundation (ASF) under one 2// or more contributor license agreements. See the NOTICE file 3// distributed with this work for additional information 4// regarding copyright ownership. The ASF licenses this file 5// to you under the Apache License, Version 2.0 (the 6// "License"); you may not use this file except in compliance 7// with the License. You may obtain a copy of the License at 8// 9// http://www.apache.org/licenses/LICENSE-2.0 10// 11// Unless required by applicable law or agreed to in writing, 12// software distributed under the License is distributed on an 13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 14// KIND, either express or implied. See the License for the 15// specific language governing permissions and limitations 16// under the License. 17 18include "common.fbs"; 19 20// Plasma protocol specification 21namespace plasma.flatbuf; 22 23enum MessageType:long { 24 // Message that gets send when a client hangs up. 25 PlasmaDisconnectClient = 0, 26 // Create a new object. 27 PlasmaCreateRequest, 28 PlasmaCreateReply, 29 PlasmaCreateAndSealRequest, 30 PlasmaCreateAndSealReply, 31 PlasmaAbortRequest, 32 PlasmaAbortReply, 33 // Seal an object. 34 PlasmaSealRequest, 35 PlasmaSealReply, 36 // Get an object that is stored on the local Plasma store. 37 PlasmaGetRequest, 38 PlasmaGetReply, 39 // Release an object. 40 PlasmaReleaseRequest, 41 PlasmaReleaseReply, 42 // Delete an object. 43 PlasmaDeleteRequest, 44 PlasmaDeleteReply, 45 // See if the store contains an object (will be deprecated). 46 PlasmaContainsRequest, 47 PlasmaContainsReply, 48 // List all objects in the store. 49 PlasmaListRequest, 50 PlasmaListReply, 51 // Get information for a newly connecting client. 52 PlasmaConnectRequest, 53 PlasmaConnectReply, 54 // Make room for new objects in the plasma store. 55 PlasmaEvictRequest, 56 PlasmaEvictReply, 57 // Subscribe to a list of objects or to all objects. 58 PlasmaSubscribeRequest, 59 // Unsubscribe. 60 PlasmaUnsubscribeRequest, 61 // Sending and receiving data. 62 // PlasmaDataRequest initiates sending the data, there will be one 63 // such message per data transfer. 64 PlasmaDataRequest, 65 // PlasmaDataReply contains the actual data and is sent back to the 66 // object store that requested the data. For each transfer, multiple 67 // reply messages get sent. Each one contains a fixed number of bytes. 68 PlasmaDataReply, 69 // Object notifications. 70 PlasmaNotification, 71 // Set memory quota for a client. 72 PlasmaSetOptionsRequest, 73 PlasmaSetOptionsReply, 74 // Get debugging information from the store. 75 PlasmaGetDebugStringRequest, 76 PlasmaGetDebugStringReply, 77 // Create and seal a batch of objects. This should be used to save 78 // IPC for creating many small objects. 79 PlasmaCreateAndSealBatchRequest, 80 PlasmaCreateAndSealBatchReply, 81 // Touch a number of objects to bump their position in the LRU cache. 82 PlasmaRefreshLRURequest, 83 PlasmaRefreshLRUReply, 84} 85 86enum PlasmaError:int { 87 // Operation was successful. 88 OK, 89 // Trying to create an object that already exists. 90 ObjectExists, 91 // Trying to access an object that doesn't exist. 92 ObjectNotFound, 93 // Trying to create an object but there isn't enough space in the store. 94 OutOfMemory, 95 // Trying to delete an object but it's not sealed. 96 ObjectNotSealed, 97 // Trying to delete an object but it's in use. 98 ObjectInUse, 99} 100 101// Plasma store messages 102 103struct PlasmaObjectSpec { 104 // Index of the memory segment (= memory mapped file) that 105 // this object is allocated in. 106 segment_index: int; 107 // The offset in bytes in the memory mapped file of the data. 108 data_offset: ulong; 109 // The size in bytes of the data. 110 data_size: ulong; 111 // The offset in bytes in the memory mapped file of the metadata. 112 metadata_offset: ulong; 113 // The size in bytes of the metadata. 114 metadata_size: ulong; 115 // Device to create buffer on. 116 device_num: int; 117} 118 119table PlasmaSetOptionsRequest { 120 // The name of the client. 121 client_name: string; 122 // The size of the output memory limit in bytes. 123 output_memory_quota: long; 124} 125 126table PlasmaSetOptionsReply { 127 // Whether setting options succeeded. 128 error: PlasmaError; 129} 130 131table PlasmaGetDebugStringRequest { 132} 133 134table PlasmaGetDebugStringReply { 135 // The debug string from the server. 136 debug_string: string; 137} 138 139table PlasmaCreateRequest { 140 // ID of the object to be created. 141 object_id: string; 142 // Whether to evict other objects to make room for this one. 143 evict_if_full: bool; 144 // The size of the object's data in bytes. 145 data_size: ulong; 146 // The size of the object's metadata in bytes. 147 metadata_size: ulong; 148 // Device to create buffer on. 149 device_num: int; 150} 151 152table CudaHandle { 153 handle: [ubyte]; 154} 155 156table PlasmaCreateReply { 157 // ID of the object that was created. 158 object_id: string; 159 // The object that is returned with this reply. 160 plasma_object: PlasmaObjectSpec; 161 // Error that occurred for this call. 162 error: PlasmaError; 163 // The file descriptor in the store that corresponds to the file descriptor 164 // being sent to the client right after this message. 165 store_fd: int; 166 // The size in bytes of the segment for the store file descriptor (needed to 167 // call mmap). 168 mmap_size: long; 169 // CUDA IPC Handle for objects on GPU. 170 ipc_handle: CudaHandle; 171} 172 173table PlasmaCreateAndSealRequest { 174 // ID of the object to be created. 175 object_id: string; 176 // Whether to evict other objects to make room for this one. 177 evict_if_full: bool; 178 // The object's data. 179 data: string; 180 // The object's metadata. 181 metadata: string; 182 // Hash of the object data. 183 digest: string; 184} 185 186table PlasmaCreateAndSealReply { 187 // Error that occurred for this call. 188 error: PlasmaError; 189} 190 191table PlasmaCreateAndSealBatchRequest { 192 object_ids: [string]; 193 // Whether to evict other objects to make room for these objects. 194 evict_if_full: bool; 195 data: [string]; 196 metadata: [string]; 197 digest: [string]; 198} 199 200table PlasmaCreateAndSealBatchReply { 201 // Error that occurred for this call. 202 error: PlasmaError; 203} 204 205table PlasmaAbortRequest { 206 // ID of the object to be aborted. 207 object_id: string; 208} 209 210table PlasmaAbortReply { 211 // ID of the object that was aborted. 212 object_id: string; 213} 214 215table PlasmaSealRequest { 216 // ID of the object to be sealed. 217 object_id: string; 218 // Hash of the object data. 219 digest: string; 220} 221 222table PlasmaSealReply { 223 // ID of the object that was sealed. 224 object_id: string; 225 // Error code. 226 error: PlasmaError; 227} 228 229table PlasmaGetRequest { 230 // IDs of the objects stored at local Plasma store we are getting. 231 object_ids: [string]; 232 // The number of milliseconds before the request should timeout. 233 timeout_ms: long; 234} 235 236table PlasmaGetReply { 237 // IDs of the objects being returned. 238 // This number can be smaller than the number of requested 239 // objects if not all requested objects are stored and sealed 240 // in the local Plasma store. 241 object_ids: [string]; 242 // Plasma object information, in the same order as their IDs. The number of 243 // elements in both object_ids and plasma_objects arrays must agree. 244 plasma_objects: [PlasmaObjectSpec]; 245 // A list of the file descriptors in the store that correspond to the file 246 // descriptors being sent to the client. The length of this list is the number 247 // of file descriptors that the store will send to the client after this 248 // message. 249 store_fds: [int]; 250 // Size in bytes of the segment for each store file descriptor (needed to call 251 // mmap). This list must have the same length as store_fds. 252 mmap_sizes: [long]; 253 // The number of elements in both object_ids and plasma_objects arrays must agree. 254 handles: [CudaHandle]; 255} 256 257table PlasmaReleaseRequest { 258 // ID of the object to be released. 259 object_id: string; 260} 261 262table PlasmaReleaseReply { 263 // ID of the object that was released. 264 object_id: string; 265 // Error code. 266 error: PlasmaError; 267} 268 269table PlasmaDeleteRequest { 270 // The number of objects to delete. 271 count: int; 272 // ID of the object to be deleted. 273 object_ids: [string]; 274} 275 276table PlasmaDeleteReply { 277 // The number of objects to delete. 278 count: int; 279 // ID of the object that was deleted. 280 object_ids: [string]; 281 // Error code. 282 errors: [PlasmaError]; 283} 284 285table PlasmaContainsRequest { 286 // ID of the object we are querying. 287 object_id: string; 288} 289 290table PlasmaContainsReply { 291 // ID of the object we are querying. 292 object_id: string; 293 // 1 if the object is in the store and 0 otherwise. 294 has_object: int; 295} 296 297table PlasmaListRequest { 298} 299 300table PlasmaListReply { 301 objects: [ObjectInfo]; 302} 303 304// PlasmaConnect is used by a plasma client the first time it connects with the 305// store. This is not really necessary, but is used to get some information 306// about the store such as its memory capacity. 307 308table PlasmaConnectRequest { 309} 310 311table PlasmaConnectReply { 312 // The memory capacity of the store. 313 memory_capacity: long; 314} 315 316table PlasmaEvictRequest { 317 // Number of bytes that shall be freed. 318 num_bytes: ulong; 319} 320 321table PlasmaEvictReply { 322 // Number of bytes that have been freed. 323 num_bytes: ulong; 324} 325 326table PlasmaSubscribeRequest { 327} 328 329table PlasmaNotification { 330 object_info: [ObjectInfo]; 331} 332 333table PlasmaDataRequest { 334 // ID of the object that is requested. 335 object_id: string; 336 // The host address where the data shall be sent to. 337 address: string; 338 // The port of the manager the data shall be sent to. 339 port: int; 340} 341 342table PlasmaDataReply { 343 // ID of the object that will be sent. 344 object_id: string; 345 // Size of the object data in bytes. 346 object_size: ulong; 347 // Size of the metadata in bytes. 348 metadata_size: ulong; 349} 350 351table PlasmaRefreshLRURequest { 352 // ID of the objects to be bumped in the LRU cache. 353 object_ids: [string]; 354} 355 356table PlasmaRefreshLRUReply { 357} 358