A container for Blobs. More...

#include <bucket.h>

Collaboration diagram for hermes::api::Bucket:

[legend]

Public Member Functions
	Bucket ()
	Default constructor. More...

	Bucket (const std::string &initial_name, std::shared_ptr< Hermes > const &h, Context ctx=Context())
	Constructor. More...

	~Bucket ()
	Releases the Bucket, decrementing its reference count. More...

std::string	GetName () const
	Get the user-facing name of the Bucket. More...

u64	GetId () const
	Get the internal ID of the bucket. More...

bool	IsValid () const
	Return true if the Bucket is valid. More...

size_t	GetTotalBlobSize ()
	Return the total size in bytes of all Blobs in this Bucket. More...

template<typename T >
Status	Put (const std::string &name, const std::vector< T > &data)
	Put a Blob in this Bucket. More...

template<typename T >
Status	Put (const std::string &name, const std::vector< T > &data, Context &ctx)
	Put a Blob in this Bucket using context. More...

Status	Put (const std::string &name, const u8 *data, size_t size)
	Put a Blob in this Bucket. More...

Status	Put (const std::string &name, const u8 *data, size_t size, const Context &ctx)

template<typename T >
Status	Put (const std::vector< std::string > &names, const std::vector< std::vector< T >> &blobs)
	Put a vector of Blobs. More...

template<typename T >
Status	Put (const std::vector< std::string > &names, const std::vector< std::vector< T >> &blobs, const Context &ctx)

size_t	GetBlobSize (const std::string &name, const Context &ctx)
	Get the size in bytes of the Blob referred to by `name`. More...

size_t	GetBlobSize (Arena *arena, const std::string &name, const Context &ctx)

size_t	Get (const std::string &name, Blob &user_blob)
	Get a blob from this Bucket. More...

size_t	Get (const std::string &name, Blob &user_blob, const Context &ctx)

std::vector< size_t >	Get (const std::vector< std::string > &names, std::vector< Blob > &blobs, const Context &ctx)
	Retrieve multiple Blobs in one call. More...

size_t	Get (const std::string &name, void *user_blob, size_t blob_size, const Context &ctx)

size_t	GetNext (u64 blob_index, Blob &user_blob)
	Given an ordering of Blobs, retrieves the Blob at index `blob_index` + 1. More...

size_t	GetNext (u64 blob_index, Blob &user_blob, const Context &ctx)

size_t	GetNext (u64 blob_index, void *user_blob, size_t blob_size, const Context &ctx)

std::vector< size_t >	GetNext (u64 blob_index, u64 count, std::vector< Blob > &blobs, const Context &ctx)
	Retrieves multiple blobs from the Bucket. More...

template<class Predicate >
Status	GetV (void *user_blob, Predicate pred, Context &ctx)
	Get Blob%(s) from this Bucket according to a predicate. More...

Status	DeleteBlob (const std::string &name)
	Delete a Blob from this Bucket. More...

Status	DeleteBlob (const std::string &name, const Context &ctx)

Status	RenameBlob (const std::string &old_name, const std::string &new_name)
	Rename a Blob in this Bucket. More...

Status	RenameBlob (const std::string &old_name, const std::string &new_name, const Context &ctx)

bool	ContainsBlob (const std::string &name)
	Returns true if the Bucket contains a Blob called `name`. More...

bool	BlobIsInSwap (const std::string &name)
	Return true if the Blob `name` is in swap space. More...

template<class Predicate >
std::vector< std::string >	GetBlobNames (Predicate pred, Context &ctx)
	Get a list of blob names filtered by `pred`. More...

Status	Rename (const std::string &new_name)
	Rename this Bucket. More...

Status	Rename (const std::string &new_name, const Context &ctx)

Status	Persist (const std::string &file_name)
	Save this Bucket's Blobs to persistent storage. More...

Status	Persist (const std::string &file_name, const Context &ctx)

void	OrganizeBlob (const std::string &blob_name, f32 epsilon, f32 custom_importance=-1.f)
	Allign `blob_name`'s access speed to its importance. More...

Status	Release ()
	Release this Bucket. More...

Status	Release (const Context &ctx)

Status	Destroy ()
	Destroy this Bucket. More...

Status	Destroy (const Context &ctx)

Public Attributes
std::shared_ptr< Hermes >	hermes_

Context	ctx_

Private Member Functions
template<typename T >
Status	PutInternal (const std::vector< std::string > &names, const std::vector< size_t > &sizes, const std::vector< std::vector< T >> &blobs, const Context &ctx)
	Internal version of Put, called by all overloads. More...

template<typename T >
Status	PlaceBlobs (std::vector< PlacementSchema > &schemas, const std::vector< std::vector< T >> &blobs, const std::vector< std::string > &names, const Context &ctx)
	Low-level version of Put. More...

Private Attributes
std::string	name_

hermes::BucketID	id_

Detailed Description

A container for Blobs.

Constructor & Destructor Documentation

◆ Bucket() [1/2]

hermes::api::Bucket::Bucket ( )

inline

Default constructor.

Creates the "NULL" Bucket.

◆ Bucket() [2/2]

hermes::api::Bucket::Bucket	(	const std::string &	initial_name,
		std::shared_ptr< Hermes > const &	h,
		Context	ctx = `Context()`
	)

Constructor.

Create a Bucket with name initial_name, backed by Hermes instance h, with optional Context ctx.

Parameters

initial_name	The name of this Bucket.
h	An initialized Hermes instance.
ctx	An optional Context that controls the behavior of this Bucket.

Here is the call graph for this function:

◆ ~Bucket()

hermes::api::Bucket::~Bucket ( )

Releases the Bucket, decrementing its reference count.

This does not free any resources. To remove the Bucket's metadata and free its stored Blobs, see Bucket::Destroy.

Here is the call graph for this function:

Member Function Documentation

◆ GetName()

std::string hermes::api::Bucket::GetName ( ) const

Get the user-facing name of the Bucket.

Returns: The name of this Bucket.

Here is the caller graph for this function:

◆ GetId()

u64 hermes::api::Bucket::GetId ( ) const

Get the internal ID of the bucket.

The ID is the internal representation of the Bucket's name.

Returns: The internal Bucket ID.

◆ IsValid()

bool hermes::api::Bucket::IsValid ( ) const

Return true if the Bucket is valid.

A valid Bucket is one that was successfully created, contains metadata entries, has a valid ID, and has not been destroyed. An invalid Bucket cannot be used.

Returns: true if the Bucket is valid, otherwise false.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetTotalBlobSize()

size_t hermes::api::Bucket::GetTotalBlobSize ( )

Return the total size in bytes of all Blobs in this Bucket.

Returns: The total size in bytes of all Blobs in this Bucket.

Here is the call graph for this function:

◆ Put() [1/6]

template<typename T >

Status hermes::api::Bucket::Put	(	const std::string &	name,
		const std::vector< T > &	data
	)

Put a Blob in this Bucket.

Uses the Bucket's saved Context.

Parameters

name	The name of the Blob to put.
data	The Blob data.

Returns: A Status object.

Here is the caller graph for this function:

◆ Put() [2/6]

template<typename T >

Status hermes::api::Bucket::Put	(	const std::string &	name,
		const std::vector< T > &	data,
		Context &	ctx
	)

Put a Blob in this Bucket using context.

Parameters

name	BLOB name
data	BLOB data
ctx	context

Here is the call graph for this function:

◆ Put() [3/6]

Status hermes::api::Bucket::Put	(	const std::string &	name,
		const u8 *	data,
		size_t	size
	)

Put a Blob in this Bucket.

Parameters

name	The name of the Blob to Put
data	The Blob's data.
size	The size of the Blob in bytes.

Returns: A Status object.

Precondition: The Bucket must be valid.; The length of name in bytes must not exceed hermes::api::kMaxBlobNameSize.; The Blob buffer data must not be nullptr unless size is 0.

Returns: A Status object.

Here is the call graph for this function:

◆ Put() [4/6]

Status hermes::api::Bucket::Put	(	const std::string &	name,
		const u8 *	data,
		size_t	size,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

name	BLOB name
data	BLOB data
size	BLOB size
ctx	context

Here is the call graph for this function:

◆ Put() [5/6]

template<typename T >

Status hermes::api::Bucket::Put	(	const std::vector< std::string > &	names,
		const std::vector< std::vector< T >> &	blobs
	)

Put a vector of Blobs.

Parameters

names	1 or more names, each of which is no longer than kMaxBlobNameSize bytes.
blobs	1 or more Blobs.

Precondition: The length of names and blobs should be equal.

Returns: A Status object.

Here is the call graph for this function:

◆ Put() [6/6]

template<typename T >

Status hermes::api::Bucket::Put	(	const std::vector< std::string > &	names,
		const std::vector< std::vector< T >> &	blobs,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

names	BLOB names
blobs	BLOB data
ctx	context

Here is the call graph for this function:

◆ GetBlobSize() [1/2]

size_t hermes::api::Bucket::GetBlobSize	(	const std::string &	name,
		const Context &	ctx
	)

Get the size in bytes of the Blob referred to by name.

Parameters

name	The name of the Blob to query.
ctx	context

Here is the caller graph for this function:

◆ GetBlobSize() [2/2]

size_t hermes::api::Bucket::GetBlobSize	(	Arena *	arena,
		const std::string &	name,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

arena	An Arena backed by allocated memory.
name	The name of the Blob to query.
ctx	context

Here is the call graph for this function:

◆ Get() [1/4]

size_t hermes::api::Bucket::Get	(	const std::string &	name,
		Blob &	user_blob
	)

Get a blob from this Bucket.

If if the size of user_blob is 0, return the minimum buffer size needed to contain the Blob name, otherwise copy user_blob.size() bytes to user_blob and return the number of bytes copied.

Parameters

name	The name of the Blob to get.
user_blob	User-provided storage for the retrieved Blob.

Returns: The size in bytes of the Blob.

Here is the caller graph for this function:

◆ Get() [2/4]

size_t hermes::api::Bucket::Get	(	const std::string &	name,
		Blob &	user_blob,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

name	The name of the Blob to get.
user_blob	User-provided storage for the retrieved Blob.
ctx	context

Here is the call graph for this function:

◆ Get() [3/4]

std::vector< size_t > hermes::api::Bucket::Get	(	const std::vector< std::string > &	names,
		std::vector< Blob > &	blobs,
		const Context &	ctx
	)

Retrieve multiple Blobs in one call.

Parameters

names	A list of names of the Blobs to get.
blobs	User-provided storage for the retrieved Blobs.
ctx	The Context for this Get.

Returns: The sizes in bytes of the Blobs.

Here is the call graph for this function:

◆ Get() [4/4]

size_t hermes::api::Bucket::Get	(	const std::string &	name,
		void *	user_blob,
		size_t	blob_size,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Here is the call graph for this function:

◆ GetNext() [1/4]

size_t hermes::api::Bucket::GetNext	(	u64	blob_index,
		Blob &	user_blob
	)

Given an ordering of Blobs, retrieves the Blob at index blob_index + 1.

By default Blobs are arranged in the order in which they were Put. If user_blob.size() == 0, return the minimum buffer size needed. If user_blob.size() > 0, copy user_blob.size() bytes to user_blob and return user_blob.size()

Parameters

blob_index	The starting index.
user_blob	User-provided memory for the Blob.

Returns: The size in bytes of the retrieved Blob.

Here is the caller graph for this function:

◆ GetNext() [2/4]

size_t hermes::api::Bucket::GetNext	(	u64	blob_index,
		Blob &	user_blob,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

blob_index	The starting index.
user_blob	User-provided memory for the Blob.
ctx	context

Here is the call graph for this function:

◆ GetNext() [3/4]

size_t hermes::api::Bucket::GetNext	(	u64	blob_index,
		void *	user_blob,
		size_t	blob_size,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

blob_index	The starting index.
user_blob	User-provided memory for the Blob.
blob_size	Blob size
ctx	context

Here is the call graph for this function:

◆ GetNext() [4/4]

std::vector< size_t > hermes::api::Bucket::GetNext	(	u64	blob_index,
		u64	count,
		std::vector< Blob > &	blobs,
		const Context &	ctx
	)

Retrieves multiple blobs from the Bucket.

The Blobs retrieved are the next ones from the passed blob_index

Here is the call graph for this function:

◆ GetV()

template<class Predicate >

Status hermes::api::Bucket::GetV	(	void *	user_blob,
		Predicate	pred,
		Context &	ctx
	)

Get Blob%(s) from this Bucket according to a predicate.

Todo:: Not implemented yet.

Returns: A Status object.

◆ DeleteBlob() [1/2]

Status hermes::api::Bucket::DeleteBlob ( const std::string & name )

Delete a Blob from this Bucket.

Parameters

name	The name of the Blob to delete.

Returns: A Status object.

◆ DeleteBlob() [2/2]

Status hermes::api::Bucket::DeleteBlob	(	const std::string &	name,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

name	The name of the Blob to delete.
ctx	context

Here is the call graph for this function:

◆ RenameBlob() [1/2]

Status hermes::api::Bucket::RenameBlob	(	const std::string &	old_name,
		const std::string &	new_name
	)

Rename a Blob in this Bucket.

Parameters

old_name	The Blob to rename.
new_name	The desired new name of the Blob.

Precondition: The size in bytes of new_name must be <= to kMaxBlobNameSize.

Returns: A Status object.

◆ RenameBlob() [2/2]

Status hermes::api::Bucket::RenameBlob	(	const std::string &	old_name,
		const std::string &	new_name,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

old_name	The Blob to rename.
new_name	The desired new name of the Blob.
ctx	context

Here is the call graph for this function:

◆ ContainsBlob()

bool hermes::api::Bucket::ContainsBlob ( const std::string & name )

Returns true if the Bucket contains a Blob called name.

Parameters

name	The name of the Blob to check.

Returns: true if the Blob name is in this Bucket, otherwise false.

Here is the call graph for this function:

◆ BlobIsInSwap()

bool hermes::api::Bucket::BlobIsInSwap ( const std::string & name )

Return true if the Blob name is in swap space.

Parameters

name	The name of the Blob to check.

Returns: true if the Blob called name in this Bucket is in swap space, otherwise false.

Here is the call graph for this function:

◆ GetBlobNames()

template<class Predicate >

std::vector< std::string > hermes::api::Bucket::GetBlobNames	(	Predicate	pred,
		Context &	ctx
	)

Get a list of blob names filtered by pred.

Todo:: Not implemented yet.

◆ Rename() [1/2]

Status hermes::api::Bucket::Rename ( const std::string & new_name )

Rename this Bucket.

Parameters

new_name A new name for the Bucket.

Precondition: The length of new_name in bytes should be less than kMaxBucketNameSize.

Returns: A Status object.

◆ Rename() [2/2]

Status hermes::api::Bucket::Rename	(	const std::string &	new_name,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

new_name	A new name for the Bucket.
ctx	context

Here is the call graph for this function:

◆ Persist() [1/2]

Status hermes::api::Bucket::Persist ( const std::string & file_name )

Save this Bucket's Blobs to persistent storage.

The blobs are written in the same order in which they were Put.

Parameters

file_name The name of the file to persist the Blob's to.

Returns: A Status object.

◆ Persist() [2/2]

Status hermes::api::Bucket::Persist	(	const std::string &	file_name,
		const Context &	ctx
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

file_name	The name of the file to persist the Blob's to.
ctx	context

Here is the call graph for this function:

◆ OrganizeBlob()

void hermes::api::Bucket::OrganizeBlob	(	const std::string &	blob_name,
		f32	epsilon,
		f32	custom_importance = `-1.f`
	)

Allign blob_name's access speed to its importance.

Parameters

blob_name	The name of the Blob to organize.
epsilon	The threshold within which the Blob's access time should match its importance. Constraint: 0 < epsilon <= 1.
custom_importance	A measure of importance that overrides the internal importance of a Blob. Constraint: 0 <= custom_importance <= 1, where 1 signifies the most important Blob. By default the internal, statistics-based measure of importance is used.

Here is the call graph for this function:

◆ Release() [1/2]

Status hermes::api::Bucket::Release ( )

Release this Bucket.

This function simply decrements the refcount to this Bucket in the Hermes metadata. To free resources associated with this Bucket, call Bucket::Destroy.

Returns: A Status object.

Here is the caller graph for this function:

◆ Release() [2/2]

Status hermes::api::Bucket::Release ( const Context & ctx )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

ctx	The Context for this call.

Here is the call graph for this function:

◆ Destroy() [1/2]

Status hermes::api::Bucket::Destroy ( )

Destroy this Bucket.

Deletes all metadata and Blob's associated with this Bucket.

Precondition: The Bucket must have a reference count of 1. Other ranks must first Bucket::Close the Bucket.

Returns: A Status object.

◆ Destroy() [2/2]

Status hermes::api::Bucket::Destroy ( const Context & ctx )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

ctx	The Context for this call..

Here is the call graph for this function:

◆ PutInternal()

template<typename T >

Status hermes::api::Bucket::PutInternal	(	const std::vector< std::string > &	names,
		const std::vector< size_t > &	sizes,
		const std::vector< std::vector< T >> &	blobs,
		const Context &	ctx
	)

private

Internal version of Put, called by all overloads.

Returns: A Status object.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ PlaceBlobs()

template<typename T >

Status hermes::api::Bucket::PlaceBlobs	(	std::vector< PlacementSchema > &	schemas,
		const std::vector< std::vector< T >> &	blobs,
		const std::vector< std::string > &	names,
		const Context &	ctx
	)

private

Low-level version of Put.

Returns: A Status object.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ name_

std::string hermes::api::Bucket::name_

private

The user-facing descriptor of this Bucket.

◆ id_

hermes::BucketID hermes::api::Bucket::id_

private

The internal descriptor of this Bucket.

◆ hermes_

std::shared_ptr<Hermes> hermes::api::Bucket::hermes_

The internal Hermes instance within which to create this Bucket.

◆ ctx_

Context hermes::api::Bucket::ctx_

The api::Context that controls all operations on this Bucket.

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

/home/runner/work/hermes/hermes/src/api/bucket.h
/home/runner/work/hermes/hermes/src/api/bucket.cc

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Bucket() [1/2]

◆ Bucket() [2/2]

◆ ~Bucket()

Member Function Documentation

◆ GetName()

◆ GetId()

◆ IsValid()

◆ GetTotalBlobSize()

◆ Put() [1/6]

◆ Put() [2/6]

◆ Put() [3/6]

◆ Put() [4/6]

◆ Put() [5/6]

◆ Put() [6/6]

◆ GetBlobSize() [1/2]

◆ GetBlobSize() [2/2]

◆ Get() [1/4]

◆ Get() [2/4]

◆ Get() [3/4]

◆ Get() [4/4]

◆ GetNext() [1/4]

◆ GetNext() [2/4]

◆ GetNext() [3/4]

◆ GetNext() [4/4]

◆ GetV()

◆ DeleteBlob() [1/2]

◆ DeleteBlob() [2/2]

◆ RenameBlob() [1/2]

◆ RenameBlob() [2/2]

◆ ContainsBlob()

◆ BlobIsInSwap()

◆ GetBlobNames()

◆ Rename() [1/2]

◆ Rename() [2/2]

◆ Persist() [1/2]

◆ Persist() [2/2]

◆ OrganizeBlob()

◆ Release() [1/2]

◆ Release() [2/2]

◆ Destroy() [1/2]

◆ Destroy() [2/2]

◆ PutInternal()

◆ PlaceBlobs()

Member Data Documentation

◆ name_

◆ id_

◆ hermes_

◆ ctx_