GStreamer Buffer Synchronization documentation

Examples

This page explains what the examples included in the API references are. First explain what the library public APIs are. And after explaining what the examples of the library are and what they test

Library API

Creation

To create a Synchronizer use the static function Build

 std::shared_ptr<ISynchronizer> syncer = ISynchronizer::Build (rrsyncer::ISynchronizer::Synchronizers::kVideo);

To create Buffers, we recommend using shared pointers, for example:

 std::vector<std::shared_ptr<rrsyncer::Buffer<int>>> buffers = 
     std::vector<std::shared_ptr<rrsyncer::Buffer<int>>>(stream_count, nullptr);
 for (size_t i = 0; i < stream_count; i++) {
     buffers[i] = std::make_shared<rrsyncer::Buffer<int>>();
     buffers[i]->SetTimeStamp(i);
 }

While a buffer do not net a TimeStamp to exist, it is needed to synchronize.

Configuration

You can configure a Synchronizer using the configure function.

 std::shared_ptr<rrsyncer::ISynchronizer::Settings> settings = std::make_shared<rrsyncer::ISynchronizer::Settings>();
 settings->function = rrsyncer::ISynchronizer::Function::kNearestNeighbor;
 settings->mode = rrsyncer::ISynchronizer::OperationMode::kOnCall;
 settings->point = rrsyncer::ISynchronizer::CentralPoint::kMedian;
 settings->rate = 30;
 settings->timeout = 0;
 size_t stream_count = 3;
 syncer->Configure(settings, stream_count);

To install a callback function, you can use the InstallCallback function.

syncer->InstallCallback(Synced, rrsyncer::ISynchronizer::Event::kSynced, nullptr);

If you need to save data inside the library buffers, you can use the IBuffer getter and setter functions.

 
std::vector<priv_struct *> planes = {priv_ptr};
std::vector<uint64_t> sizes = {struct_count};
rrsyncer::Buffer<priv_struct> lib_buffer = std::make_shared<rrsyncer::Buffer<priv_struct>>();
lib_buffer->SetData(planes, sizes);
std::vector<priv_struct *> priv_structs = lib_buffers->GetData();

Operation mode

Synchronizer has two operation modes: OnCall and OnConsensus. OnCall drops the buffer when the pop function is used and the synced callback is used for preprocessing if needed, while OnConsensus drops the buffer in the synced callback, and the pop function will return an error code. OnCall is designed to work with synchronous workflows, and OnConsensus with asynchronous.

Push

You can push to the library using the individual function.

syncer->PushBuffer(buffers.at(0), 0);
syncer->PushBuffer(buffers.at(0), 1);
syncer->PushBuffer(buffers.at(0), 2);

Or using the group function

syncer->PushBuffers(buffersptr);

Pop

You can retrieve the synced buffers using the pop function.

std::vector<std::shared_ptr<rrsyncer::IBuffer>> bufferspopped =
    std::vector<std::shared_ptr<rrsyncer::IBuffer>>(stream_count, nullptr);
syncer->PopBuffers(bufferspopped);

If you configure the Synchronizer in consensus mode

  settings->mode = rrsyncer::ISynchronizer::OperationMode::kOnConsensus;

The PopBuffer function should not be used, as the Synchronizer uses the synced callback function to submit the buffer in your code.

Examples

hello-syncer

This example shows how to create a synchronizer and check that the lib is linked using the debug hello function.

To create a synchronizer, use:

std::shared_ptr<rrsyncer::ISynchronizer> syncer_ptr =
rrsyncer::ISynchronizer::Build(
rrsyncer::ISynchronizer::Synchronizers::kVideo);

buffer-functions

This example shows how to create a buffer and push or pop from the synchronizer using the synchronizer buffer functions. To use the push function

std::shared_ptr<rrsyncer::Buffer<int>> buffer =
 std::make_shared<rrsyncer::Buffer<int>>();
syncer_ptr->PushBuffer(buffer, 0);
syncer_ptr->PushBuffer(buffer, 1);
syncer_ptr->PushBuffer(buffer, 2);

To use the pop function

std::vector<std::shared_ptr<rrsyncer::IBuffer>> bufferspopped =
std::vector<std::shared_ptr<rrsyncer::IBuffer>>(stream_count, nullptr);
syncer_ptr->PopBuffers(bufferspopped);

max-queue

This example shows how to configure the synchronizer to limit the queue sizes and how to install a drop callback to dispose of the buffers.

To configure the limit

settings->leak = rrsyncer::ISynchronizer::LeakMode::KDownStream;
settings->queue_limit = 3;

To install Callbacks

auto ret = syncer_ptr->InstallCallback(
    Drop, rrsyncer::ISynchronizer::Event::kDrop, nullptr);

MT-example

This example shows the threading behavior of blocking depending of the synchronizer config. With OnCall mode the pop operation is blocking, and with OnConsensus mode the push functions are blocking while the sync process is made. These examples show the case with config with OnCall mode.

sync-example

This example shows the possible cases and errors when sync, including the three possible actions when sync:

Not enough buffer to sync
Drop an old buffer
Sync correctly

Index

❯