A memory buffer. More...

#include "vdo-frame.h"

Include dependency graph for vdo-buffer.h:

This graph shows which files directly or indirectly include this file:

Functions
VdoBuffer *	vdo_buffer_new (gint fd, gsize capacity, guint64 offset, gpointer opaque)
	Create a buffer which is owned by an external framework. More...

VdoBuffer *	vdo_buffer_new_full (gint fd, gsize capacity, guint64 offset, gpointer opaque, VdoMap *settings)
	Create a buffer with custom buffer properties. More...

guint32	vdo_buffer_get_id (VdoBuffer *self)
	Returns an id representing the `VdoBuffer`. More...

gint	vdo_buffer_get_fd (VdoBuffer *self)
	Returns a file descriptor representing the `VdoBuffer`. More...

gint64	vdo_buffer_get_offset (VdoBuffer *self)
	Returns file offset to the `VdoBuffer`. More...

gsize	vdo_buffer_get_capacity (VdoBuffer *self)
	Returns the entire buffer capacity of the `VdoBuffer`. More...

gboolean	vdo_buffer_is_complete (VdoBuffer *self)
	Indicates whether the buffer is complete or not. More...

gpointer	vdo_buffer_get_opaque (VdoBuffer *self)
	Opaque pointers contain user provided custom information. More...

gpointer	vdo_buffer_get_data (VdoBuffer *self)
	Returns a pointer to the underlying buffer. More...

VdoFrame *	vdo_buffer_get_frame (VdoBuffer *self)
	Returns a pointer to the underlying frame. More...

Detailed Description

A memory buffer.

Function Documentation

◆ vdo_buffer_get_capacity()

gsize vdo_buffer_get_capacity ( VdoBuffer * self )

Returns the entire buffer capacity of the VdoBuffer.

For alignment purposes the buffer may be larger than requested.

Parameters

self	A VdoBuffer.

Returns: Capacity of the buffer in bytes.

◆ vdo_buffer_get_data()

gpointer vdo_buffer_get_data ( VdoBuffer * self )

Returns a pointer to the underlying buffer.

Beware this pointer is only valid for as long as the VdoBuffer itself is valid.

Parameters

self	A VdoBuffer.

Returns: A pointer to the buffer data or NULL if allocation failed.

◆ vdo_buffer_get_fd()

gint vdo_buffer_get_fd ( VdoBuffer * self )

Returns a file descriptor representing the VdoBuffer.

Parameters

self	A VdoBuffer.

Returns: A file descriptor or -1 on error.

◆ vdo_buffer_get_frame()

VdoFrame* vdo_buffer_get_frame ( VdoBuffer * self )

Returns a pointer to the underlying frame.

Beware this pointer is only valid for as long as the VdoBuffer itself is valid.

while (1) {
    VdoBuffer *buffer = vdo_stream_get_buffer(stream, &error);
    VdoFrame  *frame  = vdo_buffer_get_frame(buffer);
    if (!frame) { // An error occurred
        // Only log unexpected errors (ignore server maintenance etc.)
        if (!vdo_error_is_expected(&error))
            fprintf(stderr, "%s\n", err->message);
        // Exit and try to create a new stream
        break;
    }
    // Extract the timestamp from the frame
    uint64_t timestamp = vdo_frame_get_timestamp(frame);
    g_object_unref(buffer); // Both 'buffer' and 'frame' are now invalid
}

Parameters

self	A VdoBuffer or `NULL`

Returns: A pointer to the frame or NULL if self was NULL

◆ vdo_buffer_get_id()

guint32 vdo_buffer_get_id ( VdoBuffer * self )

Returns an id representing the VdoBuffer.

The id is not guaranteed to be globally unique.

Parameters

self	A VdoBuffer.

Returns: The id.

◆ vdo_buffer_get_offset()

gint64 vdo_buffer_get_offset ( VdoBuffer * self )

Returns file offset to the VdoBuffer.

Parameters

self	A VdoBuffer.

Returns: The file offset.

◆ vdo_buffer_get_opaque()

gpointer vdo_buffer_get_opaque ( VdoBuffer * self )

Opaque pointers contain user provided custom information.

The opaque pointer has no predefined meaning inside the vdo framework itself, it is meant to facilitate interoperability with other existing frameworks as well as caching the buffer data pointer(see vdo_buffer_get_data).

typedef struct {
  gpointer buffer_data;
  size_t   framework_data;
} external_framework_t;
// Allocate and Enqueue a Buffer
external_framework_t *opaque_in = g_new0(external_framework_t, 1);
VdoBuffer *buffer_in = vdo_stream_buffer_alloc(stream, opaque_in, NULL);
opaque_in->buffer_data = vdo_buffer_get_data(buffer_in);
opaque_in->framework_data = 0x12345678;
vdo_stream_buffer_enqueue(stream, buffer_in);
// Retrieve filled Buffer
VdoBuffer *buffer_out = vdo_stream_get_buffer(stream, NULL);
external_framework_t *opaque_out = vdo_frame_get_opaque(buffer_out);
assert(opaque_in == opaque_out);

Parameters

self	A VdoBuffer.

Returns: A pointer to the opaque user provided information

◆ vdo_buffer_is_complete()

gboolean vdo_buffer_is_complete ( VdoBuffer * self )

Indicates whether the buffer is complete or not.

As the size of compressed objects is not known in advance they may have to span multiple buffers. As soon as an entire object has arrived it will be indicated by TRUE.

size_t number_of_frames = 0;
while (1) {
    VdoBuffer *buffer = vdo_stream_get_buffer(stream, &error);
    if (vdo_buffer_is_complete(buffer))
        number_of_frames += 1;
    g_object_unref(buffer);
}

Parameters

self	A VdoBuffer.

Returns: TRUE means complete, FALSE means incomplete

◆ vdo_buffer_new()

VdoBuffer* vdo_buffer_new	(	gint	fd,
		gsize	capacity,
		guint64	offset,
		gpointer	opaque
	)

Create a buffer which is owned by an external framework.

Default: VDO_BUFFER_ACCESS_CPU_RD (suitable for normal consumers) The fd will not be closed by g_object_unref.

Parameters

fd	A mmap compatible file descriptor
capacity	The buffer capacity
offset	The offset to the start of the buffer
opaque	The opaque custom information associated with the buffer

Returns: A VdoBuffer. Free with g_object_unref().

◆ vdo_buffer_new_full()

VdoBuffer* vdo_buffer_new_full	(	gint	fd,
		gsize	capacity,
		guint64	offset,
		gpointer	opaque,
		VdoMap *	settings
	)

Create a buffer with custom buffer properties.

Default: VDO_BUFFER_ACCESS_ANY_RW (suitable for producers) The fd will not be closed by g_object_unref.

VdoMap *settings = vdo_map_new();
vdo_map_set_uint32(settings, "buffer.access", VDO_BUFFER_ACCESS_ANY_RW);
VdoBuffer *buffer = vdo_buffer_new_full(fd, capacity, 0, NULL, settings);

Parameters

fd	A mmap compatible file descriptor
capacity	The buffer capacity
offset	The offset to the start of the buffer
opaque	The opaque custom information associated with the buffer
settings	Override default buffer properties such as VdoBufferAccess

Returns: A VdoBuffer. Free with g_object_unref().

Functions

Detailed Description

Function Documentation

◆ vdo_buffer_get_capacity()

◆ vdo_buffer_get_data()

◆ vdo_buffer_get_fd()

◆ vdo_buffer_get_frame()

◆ vdo_buffer_get_id()

◆ vdo_buffer_get_offset()

◆ vdo_buffer_get_opaque()

◆ vdo_buffer_is_complete()

◆ vdo_buffer_new()

◆ vdo_buffer_new_full()