[#BloombergLP-ball-RecordBuffer]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/ball.adoc[ball]::RecordBuffer
:relfileprefix: ../../
:mrdocs:

Provide a protocol (or pure interface) for managing record handles (specifically instances of `bsl::shared_ptr<Record>`).

== Synopsis

Declared in `<ball_recordbuffer.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class RecordBuffer;
----

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/RecordBuffer/2destructor.adoc[`~RecordBuffer`] [.small]#[destructor]# [.small]#[virtual]#
| Remove all record handles stored in this record buffer and destroy this record buffer.
| xref:BloombergLP/ball/RecordBuffer/back.adoc[`back`]  [.small]#[virtual]#
| Return a reference of the shared pointer referring to the record positioned at the back of this record buffer. The behavior is undefined unless this record buffer has been locked by the `beginSequence` method and `0 < length()`.
| xref:BloombergLP/ball/RecordBuffer/beginSequence.adoc[`beginSequence`]  [.small]#[virtual]#
| _Lock_ this record buffer so that a sequence of method invocations on this record buffer can occur uninterrupted by other threads. The buffer will remain _locked_ until `endSequence` is called.
| xref:BloombergLP/ball/RecordBuffer/endSequence.adoc[`endSequence`]  [.small]#[virtual]#
| _Unlock_ this record buffer, thus allowing other threads to access it. The behavior is undefined unless the buffer is already _locked_ by `beginSequence` method.
| xref:BloombergLP/ball/RecordBuffer/front.adoc[`front`]  [.small]#[virtual]#
| Return a reference of the shared pointer referring to the record positioned at the front of this record buffer. The behavior is undefined unless this record buffer has been locked by the `beginSequence` method and `0 < length()`.
| xref:BloombergLP/ball/RecordBuffer/length.adoc[`length`]  [.small]#[virtual]#
| Return the number of record handles in this record buffer.
| xref:BloombergLP/ball/RecordBuffer/popBack.adoc[`popBack`]  [.small]#[virtual]#
| Remove from this record buffer the record handle positioned at the back of the buffer. The behavior is undefined unless `0 < length()`.
| xref:BloombergLP/ball/RecordBuffer/popFront.adoc[`popFront`]  [.small]#[virtual]#
| Remove from this record buffer the record handle positioned at the front of the buffer. The behavior is undefined unless `0 < length()`.
| xref:BloombergLP/ball/RecordBuffer/pushBack.adoc[`pushBack`]  [.small]#[virtual]#
| Append the specified `handle` to the back of this record buffer. Return 0 on success, and a non‐zero value otherwise. Note that concrete implementations are permitted to remove records from the buffer in order to attempt to accommodate a `pushBack` request (which implies that, after a successful call to `pushBack`, `length` is not guaranteed to be more than one, and an unsuccessful call to `pushBack` is permitted to leave the buffer empty).
| xref:BloombergLP/ball/RecordBuffer/pushFront.adoc[`pushFront`]  [.small]#[virtual]#
| Insert the specified `handle` at the front of this record buffer. Return 0 on success, and a non‐zero value otherwise. Note that concrete implementations are permitted to remove records from the buffer in order to attempt to accommodate a `pushFront` request (which implies that, after a successful call to `pushFront`, `length` is not guaranteed to be more than one, and an unsuccessful call to `pushFront` is permitted to leave the buffer empty).
| xref:BloombergLP/ball/RecordBuffer/removeAll.adoc[`removeAll`]  [.small]#[virtual]#
| Remove all record handles stored in this record buffer. Note that `length()` is now 0.
|===


== Derived Classes

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/FixedSizeRecordBuffer.adoc[`FixedSizeRecordBuffer`] 
| This class provides a concrete, thread‐safe implementation of the `RecordBuffer` protocol. This class is a mechanism. At any time, the sum of sizes of all records contained in a `FixedSizeRecordBuffer` object _plus_ the amount of memory allocated by the `FixedSizeRecordBuffer` object itself is guaranteed to be less than or equal to an upper bound specified at creation. The class is thread‐safe, except that the methods `front` and `back` must be called after locking the buffer by invoking `beginSequence`. In order to accommodate a `pushBack` request, the records from the front end of the buffer may be removed. Similarly, in order to accommodate a `pushFront` request, the records from the back end of the buffer may be removed. If a record can not accommodate in the buffer, it is silently (but otherwise safely) discarded.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#