Seastar
High performance C++ framework for concurrent servers
Public Member Functions | Static Public Member Functions | List of all members
seastar::temporary_buffer< CharType > Class Template Reference

Detailed Description

template<typename CharType>
class seastar::temporary_buffer< CharType >

Temporary, self-managed byte buffer.

A temporary_buffer is similar to an std::string or a std::unique_ptr<char[]>, but provides more flexible memory management. A temporary_buffer can own the memory it points to, or it can be shared with another temporary_buffer, or point at a substring of a buffer. It uses a deleter to manage its memory.

A temporary_buffer should not be held indefinitely. It can be held while a request is processed, or for a similar duration, but not longer, as it can tie up more memory that its size indicates.

A buffer can be shared: two temporary_buffer objects will point to the same data, or a subset of it. See the temporary_buffer::share() method.

Unless you created a temporary_buffer yourself, do not modify its contents, as they may be shared with another user that does not expect the data to change.

Use cases for a temporary_buffer include:

Template Parameters
CharTypeunderlying character type (must be a variant of char).

#include <seastar/core/temporary_buffer.hh>

Public Member Functions

 temporary_buffer (size_t size)
 
 temporary_buffer ()
 Creates an empty temporary_buffer that does not point at anything.
 
 temporary_buffer (const temporary_buffer &)=delete
 
 temporary_buffer (temporary_buffer &&x) noexcept
 Moves a temporary_buffer.
 
 temporary_buffer (CharType *buf, size_t size, deleter d)
 
 temporary_buffer (const CharType *src, size_t size)
 
void operator= (const temporary_buffer &)=delete
 
temporary_bufferoperator= (temporary_buffer &&x) noexcept
 Moves a temporary_buffer.
 
const CharType * get () const
 Gets a pointer to the beginning of the buffer.
 
CharType * get_write ()
 
size_t size () const
 Gets the buffer size.
 
const CharType * begin () const
 Gets a pointer to the beginning of the buffer.
 
const CharType * end () const
 Gets a pointer to the end of the buffer.
 
temporary_buffer prefix (size_t size) &&
 
CharType operator[] (size_t pos) const
 
bool empty () const
 Checks whether the buffer is empty.
 
 operator bool () const
 Checks whether the buffer is not empty.
 
temporary_buffer share ()
 
temporary_buffer share (size_t pos, size_t len)
 
temporary_buffer clone () const
 
void trim_front (size_t pos)
 
void trim (size_t pos)
 
deleter release ()
 
bool operator== (const temporary_buffer< char > &o) const
 
bool operator!= (const temporary_buffer< char > &o) const
 

Static Public Member Functions

static temporary_buffer aligned (size_t alignment, size_t size)
 

Constructor & Destructor Documentation

◆ temporary_buffer() [1/3]

template<typename CharType>
seastar::temporary_buffer< CharType >::temporary_buffer ( size_t  size)
inlineexplicit

Creates a temporary_buffer of a specified size. The buffer is not shared with anyone, and is not initialized.

Parameters
sizebuffer size, in bytes

◆ temporary_buffer() [2/3]

template<typename CharType>
seastar::temporary_buffer< CharType >::temporary_buffer ( CharType *  buf,
size_t  size,
deleter  d 
)
inline

Creates a temporary_buffer with a specific deleter.

Parameters
bufbeginning of the buffer held by this temporary_buffer
sizesize of the buffer
ddeleter controlling destruction of the buffer. The deleter will be destroyed when there are no longer any users for the buffer.

◆ temporary_buffer() [3/3]

template<typename CharType>
seastar::temporary_buffer< CharType >::temporary_buffer ( const CharType *  src,
size_t  size 
)
inline

Creates a temporary_buffer containing a copy of the provided data

Parameters
srcdata buffer to be copied
sizesize of data buffer in src

Member Function Documentation

◆ aligned()

template<typename CharType>
static temporary_buffer seastar::temporary_buffer< CharType >::aligned ( size_t  alignment,
size_t  size 
)
inlinestatic

Creates a temporary_buffer object with a specified size, with memory aligned to a specific boundary.

Parameters
alignmentRequired alignment; must be a power of two and a multiple of sizeof(void *).
sizeRequired size; must be a multiple of alignment.
Returns
a new temporary_buffer object.

◆ clone()

template<typename CharType>
temporary_buffer seastar::temporary_buffer< CharType >::clone ( ) const
inline

Clone the current temporary_buffer object into a new one. This creates a temporary buffer with the same length and data but not pointing to the memory of the original object.

◆ get_write()

template<typename CharType>
CharType* seastar::temporary_buffer< CharType >::get_write ( )
inline

Gets a writable pointer to the beginning of the buffer. Use only when you are certain no user expects the buffer data not to change.

◆ operator!=()

template<typename CharType>
bool seastar::temporary_buffer< CharType >::operator!= ( const temporary_buffer< char > &  o) const
inline

Compare contents of this buffer with another buffer for inequality

Parameters
obuffer to compare with
Returns
true if and only if contents are not the same

◆ operator==()

template<typename CharType>
bool seastar::temporary_buffer< CharType >::operator== ( const temporary_buffer< char > &  o) const
inline

Compare contents of this buffer with another buffer for equality

Parameters
obuffer to compare with
Returns
true if and only if contents are the same

◆ operator[]()

template<typename CharType>
CharType seastar::temporary_buffer< CharType >::operator[] ( size_t  pos) const
inline

Reads a character from a specific position in the buffer.

Parameters
posposition to read character from; must be less than size.

◆ prefix()

template<typename CharType>
temporary_buffer seastar::temporary_buffer< CharType >::prefix ( size_t  size) &&
inline

Returns the buffer, but with a reduced size. The original buffer is consumed by this call and can no longer be used.

Parameters
sizeNew size; must be smaller than current size.
Returns
the same buffer, with a prefix removed.

◆ release()

template<typename CharType>
deleter seastar::temporary_buffer< CharType >::release ( )
inline

Stops automatic memory management. When the temporary_buffer object is destroyed, the underlying deleter will not be called. Instead, it is the caller's responsibility to destroy the deleter object when the data is no longer needed.

Returns
deleter object managing the data's lifetime.

◆ share() [1/2]

template<typename CharType>
temporary_buffer seastar::temporary_buffer< CharType >::share ( )
inline

Create a new temporary_buffer object referring to the same underlying data. The underlying deleter will not be destroyed until both the original and the clone have been destroyed.

Returns
a clone of the buffer object.

◆ share() [2/2]

template<typename CharType>
temporary_buffer seastar::temporary_buffer< CharType >::share ( size_t  pos,
size_t  len 
)
inline

Create a new temporary_buffer object referring to a substring of the same underlying data. The underlying deleter will not be destroyed until both the original and the clone have been destroyed.

Parameters
posPosition of the first character to share.
lenLength of substring to share.
Returns
a clone of the buffer object, referring to a substring.

◆ trim()

template<typename CharType>
void seastar::temporary_buffer< CharType >::trim ( size_t  pos)
inline

Remove a suffix from the buffer. The underlying data is not modified.

Parameters
posPosition of first character to drop.

◆ trim_front()

template<typename CharType>
void seastar::temporary_buffer< CharType >::trim_front ( size_t  pos)
inline

Remove a prefix from the buffer. The underlying data is not modified.

Parameters
posPosition of first character to retain.

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