Apache Arrow (C++)
A columnar in-memory analytics layer designed to accelerate big data.
Public Member Functions | List of all members
plasma::PlasmaClient Class Reference

#include <plasma/client.h>

Public Member Functions

 PlasmaClient ()
 
 ~PlasmaClient ()
 
Status Connect (const std::string &store_socket_name, const std::string &manager_socket_name, int release_delay, int num_retries=-1)
 Connect to the local plasma store and plasma manager. More...
 
Status Create (const ObjectID &object_id, int64_t data_size, uint8_t *metadata, int64_t metadata_size, uint8_t **data)
 Create an object in the Plasma Store. More...
 
Status Get (const ObjectID *object_ids, int64_t num_objects, int64_t timeout_ms, ObjectBuffer *object_buffers)
 Get some objects from the Plasma Store. More...
 
Status Release (const ObjectID &object_id)
 Tell Plasma that the client no longer needs the object. More...
 
Status Contains (const ObjectID &object_id, bool *has_object)
 Check if the object store contains a particular object and the object has been sealed. More...
 
Status Seal (const ObjectID &object_id)
 Seal an object in the object store. More...
 
Status Delete (const ObjectID &object_id)
 Delete an object from the object store. More...
 
Status Evict (int64_t num_bytes, int64_t &num_bytes_evicted)
 Delete objects until we have freed up num_bytes bytes or there are no more released objects that can be deleted. More...
 
Status Hash (const ObjectID &object_id, uint8_t *digest)
 Compute the hash of an object in the object store. More...
 
Status Subscribe (int *fd)
 Subscribe to notifications when objects are sealed in the object store. More...
 
Status GetNotification (int fd, ObjectID *object_id, int64_t *data_size, int64_t *metadata_size)
 Receive next object notification for this client if Subscribe has been called. More...
 
Status Disconnect ()
 Disconnect from the local plasma instance, including the local store and manager. More...
 
Status Fetch (int num_object_ids, const ObjectID *object_ids)
 Attempt to initiate the transfer of some objects from remote Plasma Stores. More...
 
Status Wait (int64_t num_object_requests, ObjectRequest *object_requests, int num_ready_objects, int64_t timeout_ms, int *num_objects_ready)
 Wait for (1) a specified number of objects to be available (sealed) in the local Plasma Store or in a remote Plasma Store, or (2) for a timeout to expire. More...
 
Status Transfer (const char *addr, int port, const ObjectID &object_id)
 Transfer local object to a different plasma manager. More...
 
Status Info (const ObjectID &object_id, int *object_status)
 Return the status of a given object. More...
 
int get_manager_fd ()
 Get the file descriptor for the socket connection to the plasma manager. More...
 

Constructor & Destructor Documentation

◆ PlasmaClient()

plasma::PlasmaClient::PlasmaClient ( )

◆ ~PlasmaClient()

plasma::PlasmaClient::~PlasmaClient ( )

Member Function Documentation

◆ Connect()

Status plasma::PlasmaClient::Connect ( const std::string &  store_socket_name,
const std::string &  manager_socket_name,
int  release_delay,
int  num_retries = -1 
)

Connect to the local plasma store and plasma manager.

Return the resulting connection.

Parameters
store_socket_nameThe name of the UNIX domain socket to use to connect to the Plasma store.
manager_socket_nameThe name of the UNIX domain socket to use to connect to the local Plasma manager. If this is "", then this function will not connect to a manager.
release_delayNumber of released objects that are kept around and not evicted to avoid too many munmaps.
num_retriesnumber of attempts to connect to IPC socket, default 50
Returns
The return status.

◆ Contains()

Status plasma::PlasmaClient::Contains ( const ObjectID object_id,
bool *  has_object 
)

Check if the object store contains a particular object and the object has been sealed.

The result will be stored in has_object.

Todo:
: We may want to indicate if the object has been created but not sealed.
Parameters
object_idThe ID of the object whose presence we are checking.
has_objectThe function will write true at this address if the object is present and false if it is not present.
Returns
The return status.

◆ Create()

Status plasma::PlasmaClient::Create ( const ObjectID object_id,
int64_t  data_size,
uint8_t *  metadata,
int64_t  metadata_size,
uint8_t **  data 
)

Create an object in the Plasma Store.

Any metadata for this object must be be passed in when the object is created.

Parameters
object_idThe ID to use for the newly created object.
data_sizeThe size in bytes of the space to be allocated for this object's data (this does not include space used for metadata).
metadataThe object's metadata. If there is no metadata, this pointer should be NULL.
metadata_sizeThe size in bytes of the metadata. If there is no metadata, this should be 0.
dataThe address of the newly created object will be written here.
Returns
The return status.

◆ Delete()

Status plasma::PlasmaClient::Delete ( const ObjectID object_id)

Delete an object from the object store.

This currently assumes that the object is present and has been sealed.

Todo:
We may want to allow the deletion of objects that are not present or haven't been sealed.
Parameters
object_idThe ID of the object to delete.
Returns
The return status.

◆ Disconnect()

Status plasma::PlasmaClient::Disconnect ( )

Disconnect from the local plasma instance, including the local store and manager.

Returns
The return status.

◆ Evict()

Status plasma::PlasmaClient::Evict ( int64_t  num_bytes,
int64_t &  num_bytes_evicted 
)

Delete objects until we have freed up num_bytes bytes or there are no more released objects that can be deleted.

Parameters
num_bytesThe number of bytes to try to free up.
num_bytes_evictedOut parameter for total number of bytes of space retrieved.
Returns
The return status.

◆ Fetch()

Status plasma::PlasmaClient::Fetch ( int  num_object_ids,
const ObjectID object_ids 
)

Attempt to initiate the transfer of some objects from remote Plasma Stores.

This method does not guarantee that the fetched objects will arrive locally.

For an object that is available in the local Plasma Store, this method will not do anything. For an object that is not available locally, it will check if the object are already being fetched. If so, it will not do anything. If not, it will query the object table for a list of Plasma Managers that have the object. The object table will return a non-empty list, and this Plasma Manager will attempt to initiate transfers from one of those Plasma Managers.

This function is non-blocking.

This method is idempotent in the sense that it is ok to call it multiple times.

Parameters
num_object_idsThe number of object IDs fetch is being called on.
object_idsThe IDs of the objects that fetch is being called on.
Returns
The return status.

◆ Get()

Status plasma::PlasmaClient::Get ( const ObjectID object_ids,
int64_t  num_objects,
int64_t  timeout_ms,
ObjectBuffer object_buffers 
)

Get some objects from the Plasma Store.

This function will block until the objects have all been created and sealed in the Plasma Store or the timeout expires. The caller is responsible for releasing any retrieved objects, but the caller should not release objects that were not retrieved.

Parameters
object_idsThe IDs of the objects to get.
num_objectsThe number of object IDs to get.
timeout_msThe amount of time in milliseconds to wait before this request times out. If this value is -1, then no timeout is set.
object_buffersAn array where the results will be stored. If the data size field is -1, then the object was not retrieved.
Returns
The return status.

◆ get_manager_fd()

int plasma::PlasmaClient::get_manager_fd ( )

Get the file descriptor for the socket connection to the plasma manager.

Returns
The file descriptor for the manager connection. If there is no connection to the manager, this is -1.

◆ GetNotification()

Status plasma::PlasmaClient::GetNotification ( int  fd,
ObjectID object_id,
int64_t *  data_size,
int64_t *  metadata_size 
)

Receive next object notification for this client if Subscribe has been called.

Parameters
fdThe file descriptor we are reading the notification from.
object_idOut parameter, the object_id of the object that was sealed.
data_sizeOut parameter, the data size of the object that was sealed.
metadata_sizeOut parameter, the metadata size of the object that was sealed.
Returns
The return status.

◆ Hash()

Status plasma::PlasmaClient::Hash ( const ObjectID object_id,
uint8_t *  digest 
)

Compute the hash of an object in the object store.

Parameters
object_idThe ID of the object we want to hash.
digestA pointer at which to return the hash digest of the object. The pointer must have at least kDigestSize bytes allocated.
Returns
The return status.

◆ Info()

Status plasma::PlasmaClient::Info ( const ObjectID object_id,
int *  object_status 
)

Return the status of a given object.

This method may query the object table.

Parameters
object_idThe ID of the object whose status we query.
object_statusOut parameter for object status. Can take the following values.
  • PLASMA_CLIENT_LOCAL, if object is stored in the local Plasma Store. has been already scheduled by the Plasma Manager.
  • PLASMA_CLIENT_TRANSFER, if the object is either currently being transferred or just scheduled.
  • PLASMA_CLIENT_REMOTE, if the object is stored at a remote Plasma Store.
  • PLASMA_CLIENT_DOES_NOT_EXIST, if the object doesn’t exist in the system.
Returns
The return status.

◆ Release()

Status plasma::PlasmaClient::Release ( const ObjectID object_id)

Tell Plasma that the client no longer needs the object.

This should be called after Get when the client is done with the object. After this call, the address returned by Get is no longer valid. This should be called once for each call to Get (with the same object ID).

Parameters
object_idThe ID of the object that is no longer needed.
Returns
The return status.

◆ Seal()

Status plasma::PlasmaClient::Seal ( const ObjectID object_id)

Seal an object in the object store.

The object will be immutable after this call.

Parameters
object_idThe ID of the object to seal.
Returns
The return status.

◆ Subscribe()

Status plasma::PlasmaClient::Subscribe ( int *  fd)

Subscribe to notifications when objects are sealed in the object store.

Whenever an object is sealed, a message will be written to the client socket that is returned by this method.

Parameters
fdOut parameter for the file descriptor the client should use to read notifications from the object store about sealed objects.
Returns
The return status.

◆ Transfer()

Status plasma::PlasmaClient::Transfer ( const char *  addr,
int  port,
const ObjectID object_id 
)

Transfer local object to a different plasma manager.

Parameters
addrIP address of the plasma manager we are transfering to.
portPort of the plasma manager we are transfering to.
object_idObjectID of the object we are transfering.
Returns
The return status.

◆ Wait()

Status plasma::PlasmaClient::Wait ( int64_t  num_object_requests,
ObjectRequest object_requests,
int  num_ready_objects,
int64_t  timeout_ms,
int *  num_objects_ready 
)

Wait for (1) a specified number of objects to be available (sealed) in the local Plasma Store or in a remote Plasma Store, or (2) for a timeout to expire.

This is a blocking call.

Parameters
num_object_requestsSize of the object_requests array.
object_requestsObject event array. Each element contains a request for a particular object_id. The type of request is specified in the "type" field.
  • A PLASMA_QUERY_LOCAL request is satisfied when object_id becomes available in the local Plasma Store. In this case, this function sets the "status" field to ObjectStatus_Local. Note, if the status is not ObjectStatus_Local, it will be ObjectStatus_Nonexistent, but it may exist elsewhere in the system.
  • A PLASMA_QUERY_ANYWHERE request is satisfied when object_id becomes available either at the local Plasma Store or on a remote Plasma Store. In this case, the functions sets the "status" field to ObjectStatus_Local or ObjectStatus_Remote.
num_ready_objectsThe number of requests in object_requests array that must be satisfied before the function returns, unless it timeouts. The num_ready_objects should be no larger than num_object_requests.
timeout_msTimeout value in milliseconds. If this timeout expires before min_num_ready_objects of requests are satisfied, the function returns.
num_objects_readyOut parameter for number of satisfied requests in the object_requests list. If the returned number is less than min_num_ready_objects this means that timeout expired.
Returns
The return status.

The documentation for this class was generated from the following file: