cbl::Replicator Class Reference

A replicator that syncs documents between a local database's collections and a target database. More...

#include <cbl++/Replicator.hh>

Inheritance diagram for cbl::Replicator:

Public Types
using	ChangeListener = cbl::ListenerToken<Replicator, const CBLReplicatorStatus&>
	A change listener that notifies you when the replicator's status changes.
using	DocumentReplicationListener
	A document replication listener that notifies you when documents are replicated.

Public Member Functions
	Replicator (const ReplicatorConfiguration &config)
	Creates a new replicator using the specified config.
void	start (bool resetCheckpoint=false)
	Starts a replicator, asynchronously.
void	stop ()
	Stops a running replicator, asynchronously.
void	setHostReachable (bool r)
	Informs the replicator whether it's considered possible to reach the remote host with the current network configuration.
void	setSuspended (bool s)
	Puts the replicator in or out of "suspended" state.
CBLReplicatorStatus	status () const
	Returns the replicator's current status.
std::string	correlationID () const
	Returns the ID used to correlate the replication session with the remote endpoint.
fleece::Dict	pendingDocumentIDs (Collection &collection) const
	Indicates which documents in the given collection have local changes that have not yet been pushed to the server by this replicator.
bool	isDocumentPending (std::string_view docID, Collection &collection) const
	Indicates whether the document with the given ID in the given collection has local changes that have not yet been pushed to the server by this replicator.
ChangeListener	addChangeListener (ChangeListener::Callback callback)
	Registers a listener that will be called when the replicator's status changes.
DocumentReplicationListener	addDocumentReplicationListener (DocumentReplicationListener::Callback callback)
	Registers a listener that will be called when documents are replicated.
	Replicator () noexcept
	Constructs a null reference (one that points to no object).
Replicator &	operator= (std::nullptr_t)
	Releases the underlying object and resets this to a null reference.
bool	valid () const
	Returns true if this references an object, or false if it is a null reference.
	operator bool () const
	Returns true if this references an object (same as valid).
bool	operator== (const Replicator &other) const
	Returns true if both sides reference the same object, or are both null references.
bool	operator!= (const Replicator &other) const
	Returns true if the two sides reference different objects.
CBLReplicator *_Nullable	ref () const
	Returns a pointer to the underlying C object (CBLReplicator), or NULL if this is a null reference.
	Replicator (const Replicator &other) noexcept
	Copy constructor.
	Replicator (Replicator &&other) noexcept
	Move constructor.
Replicator &	operator= (const Replicator &other) noexcept
	Copy assignment.
Replicator &	operator= (Replicator &&other) noexcept
	Move assignment.
void	clear ()
	Releases the underlying C CBLReplicator and drops the C++ collection-configuration map.

Protected Member Functions
	Replicator (CBLReplicator *_Nullable ref)
	(Internal) Constructs a reference wrapping, and retaining, a C object pointer.

Detailed Description

A replicator that syncs documents between a local database's collections and a target database.

Member Typedef Documentation

ChangeListener

using cbl::Replicator::ChangeListener = cbl::ListenerToken<Replicator, const CBLReplicatorStatus&>

A change listener that notifies you when the replicator's status changes.

Note

The listener's callback will be called on a background thread managed by the replicator. It must pay attention to thread-safety. It should not take a long time to return, or it will slow down the replicator.

DocumentReplicationListener

using cbl::Replicator::DocumentReplicationListener

Initial value:

 cbl::ListenerToken<Replicator, bool,
            const std::vector<CBLReplicatedDocument>>

A document replication listener that notifies you when documents are replicated.

Note

The listener's callback will be called on a background thread managed by the replicator. It must pay attention to thread-safety. It should not take a long time to return, or it will slow down the replicator.

Constructor & Destructor Documentation

Replicator() [1/5]

cbl::Replicator::Replicator ( const ReplicatorConfiguration & config )

inline

Creates a new replicator using the specified config.

Replicator() [2/5]

cbl::Replicator::Replicator ( )

inlinenoexcept

Constructs a null reference (one that points to no object).

Replicator() [3/5]

cbl::Replicator::Replicator ( CBLReplicator *_Nullable ref )

inlineexplicitprotected

(Internal) Constructs a reference wrapping, and retaining, a C object pointer.

Replicator() [4/5]

cbl::Replicator::Replicator ( const Replicator & other )

inlinenoexcept

Copy constructor.

Both *this and other refer to the same underlying CBLReplicator handle (its refcount is incremented) and share the collection-configuration map.

Replicator() [5/5]

cbl::Replicator::Replicator ( Replicator && other )

inlinenoexcept

Move constructor.

Takes over other's CBLReplicator handle and collection-configuration map, leaving other empty.

Member Function Documentation

addChangeListener()

ChangeListener cbl::Replicator::addChangeListener ( ChangeListener::Callback callback )

inlinenodiscard

Registers a listener that will be called when the replicator's status changes.

Parameters

callback

The callback to be invoked.

Returns

A Change Listener Token. Call ListenerToken::remove() method to remove the listener.

addDocumentReplicationListener()

DocumentReplicationListener cbl::Replicator::addDocumentReplicationListener ( DocumentReplicationListener::Callback callback )

inlinenodiscard

Registers a listener that will be called when documents are replicated.

Parameters

callback

The callback to be invoked.

Returns

A Change Listener Token. Call ListenerToken::remove() method to remove the listener.

clear()

void cbl::Replicator::clear ( )

inline

Releases the underlying C CBLReplicator and drops the C++ collection-configuration map.

After this call the object is empty (its Replicator::operator bool() const returns false).

correlationID()

std::string cbl::Replicator::correlationID ( ) const

inline

Returns the ID used to correlate the replication session with the remote endpoint.

This value is intended for logging and diagnostics, and is an empty string until the replicator receives a correlation ID from the remote endpoint.

isDocumentPending()

bool cbl::Replicator::isDocumentPending ( std::string_view docID, Collection & collection ) const

inline

Indicates whether the document with the given ID in the given collection has local changes that have not yet been pushed to the server by this replicator.

This is equivalent to, but faster than, calling Replicator::pendingDocumentIDs and checking whether the result contains docID. See that function's documentation for details.

Note

A false result means the document is not pending, or there was an error. To tell the difference, compare the error code to zero.

Warning

If the given collection is not part of the replication, an error will be thrown.

operator bool()

cbl::Replicator::operator bool ( ) const

inlineexplicit

Returns true if this references an object (same as valid).

operator!=()

bool cbl::Replicator::operator!= ( const Replicator & other ) const

inline

Returns true if the two sides reference different objects.

operator=() [1/3]

Replicator & cbl::Replicator::operator= ( const Replicator & other )

inlinenoexcept

Copy assignment.

Releases the currently-referenced handle (if any), then makes *this refer to the same CBLReplicator as other (refcount incremented) and share its collection-configuration map.

operator=() [2/3]

Replicator & cbl::Replicator::operator= ( Replicator && other )

inlinenoexcept

Move assignment.

Releases the currently-referenced handle (if any), then takes over other's CBLReplicator handle and collection-configuration map; other is left empty.

operator=() [3/3]

Replicator & cbl::Replicator::operator= ( std::nullptr_t )

inline

Releases the underlying object and resets this to a null reference.

operator==()

bool cbl::Replicator::operator== ( const Replicator & other ) const

inline

Returns true if both sides reference the same object, or are both null references.

pendingDocumentIDs()

fleece::Dict cbl::Replicator::pendingDocumentIDs ( Collection & collection ) const

inline

Indicates which documents in the given collection have local changes that have not yet been pushed to the server by this replicator.

This is of course a snapshot, that will go out of date as the replicator makes progress and/or documents are saved locally.

The result is, effectively, a set of document IDs: a dictionary whose keys are the IDs and values are true. If there are no pending documents, the dictionary is empty.

Warning

If the given collection is not part of the replication, an error will be thrown.

ref()

CBLReplicator *_Nullable cbl::Replicator::ref ( ) const

inline

Returns a pointer to the underlying C object (CBLReplicator), or NULL if this is a null reference.

setHostReachable()

void cbl::Replicator::setHostReachable ( bool r )

inline

Informs the replicator whether it's considered possible to reach the remote host with the current network configuration.

The default value is true. This only affects the replicator's behavior while it's in the Offline state: Setting it to false will cancel any pending retry and prevent future automatic retries. Setting it back to true will initiate an immediate retry.

setSuspended()

void cbl::Replicator::setSuspended ( bool s )

inline

Puts the replicator in or out of "suspended" state.

The default is false. Setting suspended=true causes the replicator to disconnect and enter Offline state; it will not attempt to reconnect while it's suspended. Setting suspended=false causes the replicator to attempt to reconnect, if it was connected when suspended, and is still in Offline state.

start()

void cbl::Replicator::start ( bool resetCheckpoint = false )

inline

Starts a replicator, asynchronously.

Does nothing if it's already started.

Note

Replicators cannot be started from within a database's transaction.

Parameters

resetCheckpoint

If true, the persistent saved state ("checkpoint") for this replication will be discarded, causing it to re-scan all documents. This significantly increases time and bandwidth (redundant docs are not transferred, but their IDs are) but can resolve unexpected problems with missing documents if one side or the other has gotten out of sync.

status()

CBLReplicatorStatus cbl::Replicator::status ( ) const

inline

Returns the replicator's current status.

stop()

void cbl::Replicator::stop ( )

inline

Stops a running replicator, asynchronously.

Does nothing if it's not already started. The replicator will call your replicator change listener if registered with an activity level of kCBLReplicatorStopped after it stops. Until then, consider it still active.

valid()

bool cbl::Replicator::valid ( ) const

inline

Returns true if this references an object, or false if it is a null reference.

---

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

• include/cbl++/Replicator.hh