tim::base::ring_buffer Struct Reference

Ring buffer implementation, with support for mmap as backend (Linux only). More...

#include "timemory/storage/ring_buffer.hpp"

Collaboration diagram for tim::base::ring_buffer:

Public Member Functions
	ring_buffer ()=default
	ring_buffer (bool _use_mmap)
	ring_buffer (size_t _size)
	ring_buffer (size_t _size, bool _use_mmap)
	~ring_buffer ()
	ring_buffer (const ring_buffer &)
	ring_buffer (ring_buffer &&) noexcept=delete
ring_buffer &	operator= (const ring_buffer &)
ring_buffer &	operator= (ring_buffer &&) noexcept=delete
bool	is_initialized () const
	Returns whether the buffer has been allocated. More...
size_t	capacity () const
	Get the total number of bytes supported. More...
void	init (size_t size)
	Creates new ring buffer. More...
void	destroy ()
	Destroy ring buffer. More...
template<typename Tp >
std::pair< size_t, Tp * >	write (Tp *in, std::enable_if_t< std::is_class< Tp >::value, int >=0)
	Write class-type data to buffer (uses placement new). More...
template<typename Tp >
std::pair< size_t, Tp * >	write (Tp *in, std::enable_if_t<!std::is_class< Tp >::value, int >=0)
	Write non-class-type data to buffer (uses memcpy). More...
template<typename Tp >
Tp *	request ()
	Request a pointer to an allocation. This is similar to a "write" except the memory is uninitialized. Typically used by allocators. If Tp is a class type, be sure to use a placement new instead of a memcpy. More...
void *	request (size_t n)
	Request a pointer to an allocation for at least. More...
template<typename Tp >
std::pair< size_t, Tp * >	read (Tp *out, std::enable_if_t< std::is_class< Tp >::value, int >=0) const
	Read class-type data from buffer (uses placement new). More...
template<typename Tp >
std::pair< size_t, Tp * >	read (Tp *out, std::enable_if_t<!std::is_class< Tp >::value, int >=0) const
	Read non-class-type data from buffer (uses memcpy). More...
template<typename Tp >
Tp *	retrieve ()
	Retrieve a pointer to the head allocation (read). More...
void *	retrieve (size_t n)
	Retrieve a pointer to the head allocation of at least. More...
size_t	count () const
	Returns number of bytes currently held by the buffer. More...
size_t	free () const
	Returns how many bytes are availiable in the buffer. More...
bool	is_empty () const
	Returns if the buffer is empty. More...
bool	is_full () const
	Returns if the buffer is full. More...
size_t	rewind (size_t n) const
	Rewind the read position n bytes. More...
void	set_use_mmap (bool)
	explicitly configure to use mmap if avail More...
bool	get_use_mmap () const
	query whether using mmap More...
std::string	as_string () const

Friends
template<typename Tp >
struct	data_storage::ring_buffer
std::ostream &	operator<< (std::ostream &os, const ring_buffer &obj)

Detailed Description

Ring buffer implementation, with support for mmap as backend (Linux only).

Definition at line 49 of file ring_buffer.hpp.

Constructor & Destructor Documentation

ring_buffer() [1/6]

tim::base::ring_buffer::ring_buffer ( )

default

ring_buffer() [2/6]

tim::base::ring_buffer::ring_buffer ( bool  _use_mmap )

inlineexplicit

Definition at line 55 of file ring_buffer.hpp.

{ set_use_mmap(_use_mmap); }

References set_use_mmap().

ring_buffer() [3/6]

tim::base::ring_buffer::ring_buffer ( size_t  _size )

inlineexplicit

Definition at line 56 of file ring_buffer.hpp.

{ init(_size); }

References init().

ring_buffer() [4/6]

tim::base::ring_buffer::ring_buffer	(	size_t	_size,
		bool	_use_mmap
	)

Definition at line 52 of file ring_buffer.cpp.

{
    set_use_mmap(_use_mmap);
    init(_size);
}

References init(), and set_use_mmap().

~ring_buffer()

tim::base::ring_buffer::~ring_buffer

(

)

Definition at line 59 of file ring_buffer.cpp.

{ destroy(); }

References destroy().

ring_buffer() [5/6]

tim::base::ring_buffer::ring_buffer

(

const ring_buffer &

rhs

)

Definition at line 62 of file ring_buffer.cpp.

: m_use_mmap{ rhs.m_use_mmap }
, m_use_mmap_explicit{ rhs.m_use_mmap_explicit }
{
    init(rhs.m_size);
}

References init().

ring_buffer() [6/6]

tim::base::ring_buffer::ring_buffer ( ring_buffer &&  )

deletenoexcept

Member Function Documentation

as_string()

std::string tim::base::ring_buffer::as_string

(

)

const

Definition at line 216 of file ring_buffer.cpp.

{
    std::ostringstream ss{};
    ss << std::boolalpha << "is_initialized: " << is_initialized()
       << ", capacity: " << capacity() << ", count: " << count() << ", free: " << free()
       << ", is_empty: " << is_empty() << ", is_full: " << is_full()
       << ", pointer: " << m_ptr << ", read count: " << m_read_count
       << ", write count: " << m_write_count;
    return ss.str();
}

References capacity(), count(), free(), is_empty(), is_full(), and is_initialized().

capacity()

size_t tim::base::ring_buffer::capacity ( ) const

inline

Get the total number of bytes supported.

Definition at line 71 of file ring_buffer.hpp.

{ return m_size; }

Referenced by as_string(), tim::data_storage::ring_buffer< Tp >::as_string(), and tim::data_storage::ring_buffer< Tp >::capacity().

count()

size_t tim::base::ring_buffer::count ( ) const

inline

Returns number of bytes currently held by the buffer.

Definition at line 116 of file ring_buffer.hpp.

{ return (m_write_count - m_read_count); }

Referenced by as_string(), tim::data_storage::ring_buffer< Tp >::as_string(), tim::data_storage::ring_buffer< Tp >::count(), free(), is_empty(), is_full(), read(), and retrieve().

destroy()

void tim::base::ring_buffer::destroy

(

)

Destroy ring buffer.

Definition at line 164 of file ring_buffer.cpp.

{
    if(m_ptr && m_init)
    {
        m_init = false;
#if defined(TIMEMORY_LINUX)
        if(!m_use_mmap)
        {
            ::free(m_ptr);
        }
        else
        {
            // Truncate file to zero, to avoid writing back memory to file, on munmap.
            if(ftruncate(m_fd, 0) < 0)
            {
                bool _cond = settings::verbose() > 0 || settings::debug();
                CONDITIONAL_PRINT_HERE(_cond,
                                       "Ring buffer failed to truncate the file "
                                       "descriptor %i\n",
                                       m_fd);
            }
            // Unmap the mapped virtual memmory.
            auto ret = munmap(m_ptr, m_size * 2);
            // Close the backing file.
            close(m_fd);
            if(ret)
                perror("munmap");
        }
#else
        ::free(m_ptr);
#endif
    }
    m_init        = false;
    m_size        = 0;
    m_read_count  = 0;
    m_write_count = 0;
    m_ptr         = nullptr;
}

References tim::plotting::close(), CONDITIONAL_PRINT_HERE, tim::debug, free(), and tim::verbose.

Referenced by ~ring_buffer(), tim::data_storage::ring_buffer< Tp >::destroy(), init(), and operator=().

free()

size_t tim::base::ring_buffer::free ( ) const

inline

Returns how many bytes are availiable in the buffer.

Definition at line 119 of file ring_buffer.hpp.

{ return (m_size - count()); }

References count().

Referenced by as_string(), tim::data_storage::ring_buffer< Tp >::as_string(), destroy(), tim::data_storage::ring_buffer< Tp >::free(), tim::data_storage::ring_buffer< Tp >::is_full(), request(), and write().

get_use_mmap()

bool tim::base::ring_buffer::get_use_mmap ( ) const

inline

query whether using mmap

Definition at line 134 of file ring_buffer.hpp.

{ return m_use_mmap; }

init()

void tim::base::ring_buffer::init

(

size_t

size

)

Creates new ring buffer.

Definition at line 84 of file ring_buffer.cpp.

{
    if(m_init)
        throw std::runtime_error(
            "tim::base::ring_buffer::init(size_t) :: already initialized");
 
    m_init = true;
 
    // Round up to multiple of page size.
    _size += units::get_page_size() - ((_size % units::get_page_size() > 0)
                                           ? (_size % units::get_page_size())
                                           : units::get_page_size());
 
    if((_size % units::get_page_size()) > 0)
    {
        std::ostringstream _oss{};
        _oss << "Error! size is not a multiple of page size: " << _size << " % "
             << units::get_page_size() << " = " << (_size % units::get_page_size());
        throw std::runtime_error(_oss.str());
    }
 
    m_size        = _size;
    m_read_count  = 0;
    m_write_count = 0;
 
    if(!m_use_mmap_explicit)
        m_use_mmap = get_env("TIMEMORY_USE_MMAP", m_use_mmap);
 
#if defined(TIMEMORY_LINUX)
    if(!m_use_mmap)
    {
        m_ptr = malloc(m_size * sizeof(char));
        return;
    }
    // Set file path depending on whether shared memory is compiled in or not.
#    ifdef SHM
    char path[] = "/dev/shm/rb-XXXXXX";
#    else
    char path[] = "/tmp/rb-XXXXXX";
#    endif /* SHM */
 
    // Create a temporary file for mmap backing.
    if((m_fd = mkstemp(path)) < 0)
        destroy();
 
    // Remove file from filesystem. Note the file is still open by the
    // process.
    // XXX there might be a security problem with this, if so, use umaks 0600.
    if(unlink(path))
        destroy();
 
    // Resize file to buffer size.
    if(ftruncate(m_fd, m_size) < 0)
        destroy();
 
    // Map twice the buffer size.
    if((m_ptr = mmap(NULL, 2 * m_size, PROT_NONE, MAP_ANONYMOUS | MAP_PRIVATE, -1, 0)) ==
       MAP_FAILED)
        destroy();
 
    // Map the temporary file into the first half of the above mapped space.
    if(mmap(m_ptr, m_size, PROT_READ | PROT_WRITE, MAP_FIXED | MAP_SHARED, m_fd, 0) ==
       MAP_FAILED)
        destroy();
 
    // Map the temporary file into the second half of the mapped space.
    // This creates two consecutive copies of the same physical memory, thus
    // allowing contiues reads and writes of the buffer.
    if(mmap(static_cast<char*>(m_ptr) + m_size, m_size, PROT_READ | PROT_WRITE,
            MAP_FIXED | MAP_SHARED, m_fd, 0) == MAP_FAILED)
        destroy();
#else
    m_use_mmap = false;
    m_ptr      = malloc(m_size * sizeof(char));
    (void) m_fd;
#endif
}

References destroy(), and tim::get_env().

Referenced by ring_buffer(), tim::data_storage::ring_buffer< Tp >::init(), and operator=().

is_empty()

bool tim::base::ring_buffer::is_empty ( ) const

inline

Returns if the buffer is empty.

Definition at line 122 of file ring_buffer.hpp.

{ return (count() == 0); }

References count().

Referenced by as_string(), tim::data_storage::ring_buffer< Tp >::is_empty(), and read().

is_full()

bool tim::base::ring_buffer::is_full ( ) const

inline

Returns if the buffer is full.

Definition at line 125 of file ring_buffer.hpp.

{ return (count() == m_size); }

References count().

Referenced by as_string().

is_initialized()

bool tim::base::ring_buffer::is_initialized ( ) const

inline

Returns whether the buffer has been allocated.

Definition at line 68 of file ring_buffer.hpp.

{ return m_init; }

Referenced by as_string(), and tim::data_storage::ring_buffer< Tp >::is_initialized().

operator=() [1/2]

ring_buffer & tim::base::ring_buffer::operator=

(

const ring_buffer &

rhs

)

Definition at line 71 of file ring_buffer.cpp.

{
    if(this == &rhs)
        return *this;
    destroy();
    m_use_mmap          = rhs.m_use_mmap;
    m_use_mmap_explicit = rhs.m_use_mmap_explicit;
    init(rhs.m_size);
    return *this;
}

References destroy(), and init().

operator=() [2/2]

ring_buffer & tim::base::ring_buffer::operator= ( ring_buffer &&  )

deletenoexcept

read() [1/2]

template<typename Tp >

std::pair< size_t, Tp * > tim::base::ring_buffer::read	(	Tp *	out,
		std::enable_if_t< std::is_class< Tp >::value, int >	= 0
	)		const

Read class-type data from buffer (uses placement new).

Definition at line 259 of file ring_buffer.hpp.

{
    if(is_empty() || out == nullptr)
        return { 0, nullptr };
 
    auto _length = sizeof(Tp);
 
    // Make sure we do not read out more than there is actually in the buffer.
    if(_length > count())
        throw std::runtime_error("ring buffer is empty");
 
    // if read count is at the tail of buffer, bump to the end of buffer
    auto _modulo = m_size - (m_read_count % m_size);
    if(_modulo < _length)
        m_read_count += _modulo;
 
    // pointer in buffer
    Tp* in = reinterpret_cast<Tp*>(read_ptr());
 
    // Copy out for BYTE, nothing magic here.
    *out = *in;
 
    // Update read count.
    m_read_count += _length;
 
    return { _length, in };
}

References count(), and is_empty().

read() [2/2]

template<typename Tp >

std::pair< size_t, Tp * > tim::base::ring_buffer::read	(	Tp *	out,
		std::enable_if_t<!std::is_class< Tp >::value, int >	= 0
	)		const

Read non-class-type data from buffer (uses memcpy).

Definition at line 289 of file ring_buffer.hpp.

{
    if(is_empty() || out == nullptr)
        return { 0, nullptr };
 
    auto _length = sizeof(Tp);
 
    using Up = typename std::remove_const<Tp>::type;
 
    // Make sure we do not read out more than there is actually in the buffer.
    if(_length > count())
        throw std::runtime_error("ring buffer is empty");
 
    // if read count is at the tail of buffer, bump to the end of buffer
    auto _modulo = m_size - (m_read_count % m_size);
    if(_modulo < _length)
        m_read_count += _modulo;
 
    // pointer in buffer
    Tp* in = reinterpret_cast<Tp*>(read_ptr());
 
    // Copy out for BYTE, nothing magic here.
    Up* _out = const_cast<Up*>(out);
    memcpy(_out, in, _length);
 
    // Update read count.
    m_read_count += _length;
 
    return { _length, in };
}

References count(), and is_empty().

request() [1/2]

template<typename Tp >

Tp * tim::base::ring_buffer::request

Request a pointer to an allocation. This is similar to a "write" except the memory is uninitialized. Typically used by allocators. If Tp is a class type, be sure to use a placement new instead of a memcpy.

Definition at line 230 of file ring_buffer.hpp.

{
    if(m_ptr == nullptr)
        return nullptr;
 
    auto _length = sizeof(Tp);
 
    // Make sure we don't put in more than there's room for, by writing no
    // more than there is free.
    if(_length > free())
        throw std::runtime_error("heap-buffer-overflow :: ring buffer is full. read data "
                                 "to avoid data corruption");
 
    // if write count is at the tail of buffer, bump to the end of buffer
    auto _modulo = m_size - (m_write_count % m_size);
    if(_modulo < _length)
        m_write_count += _modulo;
 
    // pointer in buffer
    Tp* _out = reinterpret_cast<Tp*>(write_ptr());
 
    // Update write count
    m_write_count += _length;
 
    return _out;
}

References free().

request() [2/2]

void * tim::base::ring_buffer::request

(

size_t

n

)

Request a pointer to an allocation for at least.

Parameters

n

bytes.

Definition at line 229 of file ring_buffer.cpp.

{
    if(m_ptr == nullptr)
        return nullptr;
 
    // Make sure we don't put in more than there's room for, by writing no
    // more than there is free.
    if(_length > free())
        throw std::runtime_error("heap-buffer-overflow :: ring buffer is full. read data "
                                 "to avoid data corruption");
 
    // if write count is at the tail of buffer, bump to the end of buffer
    auto _modulo = m_size - (m_write_count % m_size);
    if(_modulo < _length)
        m_write_count += _modulo;
 
    // pointer in buffer
    void* _out = write_ptr();
 
    // Update write count
    m_write_count += _length;
 
    return _out;
}

References free().

retrieve() [1/2]

template<typename Tp >

Tp * tim::base::ring_buffer::retrieve

Retrieve a pointer to the head allocation (read).

Definition at line 322 of file ring_buffer.hpp.

{
    if(m_ptr == nullptr)
        return nullptr;
 
    auto _length = sizeof(Tp);
 
    // Make sure we don't put in more than there's room for, by writing no
    // more than there is free.
    if(_length > count())
        throw std::runtime_error("ring buffer is empty");
 
    // if read count is at the tail of buffer, bump to the end of buffer
    auto _modulo = m_size - (m_read_count % m_size);
    if(_modulo < _length)
        m_read_count += _modulo;
 
    // pointer in buffer
    Tp* _out = reinterpret_cast<Tp*>(read_ptr());
 
    // Update write count
    m_read_count += _length;
 
    return _out;
}

References count().

retrieve() [2/2]

void * tim::base::ring_buffer::retrieve

(

size_t

n

)

Retrieve a pointer to the head allocation of at least.

Parameters

n	bytes (read).

Definition at line 256 of file ring_buffer.cpp.

{
    if(m_ptr == nullptr)
        return nullptr;
 
    // Make sure we don't put in more than there's room for, by writing no
    // more than there is free.
    if(_length > count())
        throw std::runtime_error("ring buffer is empty");
 
    // if read count is at the tail of buffer, bump to the end of buffer
    auto _modulo = m_size - (m_read_count % m_size);
    if(_modulo < _length)
        m_read_count += _modulo;
 
    // pointer in buffer
    void* _out = read_ptr();
 
    // Update write count
    m_read_count += _length;
 
    return _out;
}

References count().

rewind()

size_t tim::base::ring_buffer::rewind

(

size_t

n

)

const

Rewind the read position n bytes.

Definition at line 282 of file ring_buffer.cpp.

{
    if(n > m_read_count)
        n = m_read_count;
    m_read_count -= n;
    return n;
}

Referenced by tim::data_storage::ring_buffer< Tp >::rewind().

set_use_mmap()

void tim::base::ring_buffer::set_use_mmap

(

bool

_v

)

explicitly configure to use mmap if avail

Definition at line 205 of file ring_buffer.cpp.

{
    if(m_init)
        throw std::runtime_error("tim::base::ring_buffer::set_use_mmap(bool) cannot be "
                                 "called after initialization");
    m_use_mmap          = _v;
    m_use_mmap_explicit = true;
}

Referenced by ring_buffer().

write() [1/2]

template<typename Tp >

std::pair< size_t, Tp * > tim::base::ring_buffer::write	(	Tp *	in,
		std::enable_if_t< std::is_class< Tp >::value, int >	= 0
	)

Write class-type data to buffer (uses placement new).

Definition at line 166 of file ring_buffer.hpp.

{
    if(in == nullptr || m_ptr == nullptr)
        return { 0, nullptr };
 
    auto _length = sizeof(Tp);
 
    // Make sure we don't put in more than there's room for, by writing no
    // more than there is free.
    if(_length > free())
        throw std::runtime_error("heap-buffer-overflow :: ring buffer is full. read data "
                                 "to avoid data corruption");
 
    // if write count is at the tail of buffer, bump to the end of buffer
    auto _modulo = m_size - (m_write_count % m_size);
    if(_modulo < _length)
        m_write_count += _modulo;
 
    // pointer in buffer
    Tp* out = reinterpret_cast<Tp*>(write_ptr());
 
    // Copy in.
    new((void*) out) Tp{ std::move(*in) };
 
    // Update write count
    m_write_count += _length;
 
    return { _length, out };
}

References free().

write() [2/2]

template<typename Tp >

std::pair< size_t, Tp * > tim::base::ring_buffer::write	(	Tp *	in,
		std::enable_if_t<!std::is_class< Tp >::value, int >	= 0
	)

Write non-class-type data to buffer (uses memcpy).

Definition at line 198 of file ring_buffer.hpp.

{
    if(in == nullptr || m_ptr == nullptr)
        return { 0, nullptr };
 
    auto _length = sizeof(Tp);
 
    // Make sure we don't put in more than there's room for, by writing no
    // more than there is free.
    if(_length > free())
        throw std::runtime_error("heap-buffer-overflow :: ring buffer is full. read data "
                                 "to avoid data corruption");
 
    // if write count is at the tail of buffer, bump to the end of buffer
    auto _modulo = m_size - (m_write_count % m_size);
    if(_modulo < _length)
        m_write_count += _modulo;
 
    // pointer in buffer
    Tp* out = reinterpret_cast<Tp*>(write_ptr());
 
    // Copy in.
    memcpy((void*) out, in, _length);
 
    // Update write count
    m_write_count += _length;
 
    return { _length, out };
}

References free().

Friends And Related Function Documentation

data_storage::ring_buffer

template<typename Tp >

friend struct data_storage::ring_buffer

friend

Definition at line 52 of file ring_buffer.hpp.

operator<<

std::ostream & operator<< ( std::ostream &  os, const ring_buffer &  obj  )

friend

Definition at line 138 of file ring_buffer.hpp.

    {
        return os << obj.as_string();
    }

---

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

• timemory/storage/ring_buffer.hpp
• timemory/storage/ring_buffer.cpp