Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://couchbase.github.io/couchbase-lite-core/C/html/group___observer.html below:

LiteCore: Database, Document, Query Observers

A query observer, also called a "live query", notifies the client when the query's result set changes.

(Not just any time the database changes.)

This is done as follows, starting from when the first time an observer on a particular query is enabled:

1. A separate C4Query instance is created, on a separate database instance (there's one of these background database instances per C4Database.)
2. The copied query is run on a background thread, and it saves its results.
3. The query observer(s) are notified so they can see the initial results.
4. The background thread listens for changes to the database, or changes to the query parameters (c4query_setParameters). In response:
   • If it's been less than 250ms since the last time it ran the query, it first waits 500ms; during this time it ignores further database changes.
   • It runs the query.
   • It compares the new result set to the old one; if they're different, it saves the new results and notifies observers. Otherwise it does nothing.
5. This background task stops when the last observer is disabled.

Some notes on performance:

All C4Queries on a single C4Database share a single background C4Database, which can only do one thing at a time. That means multiple live queries can bog down since they have to run one after the other. The first time any query observer is added in a given C4Database, the background database instance has to be opened, which takes a few milliseconds. The first time an observer is added to a C4Query, a copy of that query has to be created and compiled by the background database, which can also take a few millseconds. Running a C4Query before adding an observer is a bit of a waste, because the query will be run twice. It's more efficient to skip running it, and instead wait for the first call to the observer. The timing logic in step 4 is a heuristic to provide low latency on occasional database changes, but prevent rapid database changes (as happen during pull replication) from running the query constantly and/or spamming observers with notifications. (The specific times are not currently alterable; they're constants in LiveQuerier.cc.)

Callback invoked by a collection/database observer.

CAUTION: This callback is called when a transaction is committed, even one made by a
different connection (C4Database instance) on the same file. This means that, if your
application is multithreaded, the callback may be running on a different thread than the
one this database instance uses. It is your responsibility to ensure thread safety.

In general, it is best to make _no_ LiteCore calls from within this callback. Instead,
use your platform event-handling API to schedule a later call from which you can read the
changes. Since this callback may be invoked many times in succession, make sure you
schedule only one call at a time.

@param observer  The observer that initiated the callback.
@param context  user-defined parameter given when registering the callback. 

Callback invoked by a document observer.

Parameters

observer The observer that initiated the callback. docID The ID of the document that changed. sequence The sequence number of the change. context user-defined parameter given when registering the callback.

Callback invoked by a query observer, notifying that the query results have changed.

The actual enumerator is not passed to the callback, but can be retrieved by calling c4queryobs_getEnumerator.

Warning

This function is called on a random background thread! Be careful of thread safety. Do not spend too long in this callback or other observers may be delayed. It's best to do nothing except schedule a call on your preferred thread/queue.

Parameters

observer The observer triggering the callback. query The C4Query that the observer belongs to. context The context parameter you passed to c4queryobs_create.

Creates a new collection observer, with a callback that will be invoked after one or more documents in the collection have changed.

Note

The caller must use a lock for Database when this function is called.

Parameters

collection The collection to observe. callback The function to call after the collection changes. context An arbitrary value that will be passed to the callback.

Returns

The new observer reference.

Identifies which documents have changed in the collection since the last time this function was called, or since the observer was created.

This function effectively "reads" changes from a stream, in whatever quantity the caller desires. Once all of the changes have been read, the observer is reset and ready to notify again.

This function is usually called in response to your C4CollectionObserverCallback being called, but it doesn't have to be; it can be called at any time (subject to thread-safety requirements, of course.)

Note

This function is thread-safe.

Warning

After calling this function, you must call c4dbobs_releaseChanges to release memory that's being referenced by the C4CollectionChanges.

Parameters

observer The observer. outChanges A caller-provided buffer of structs into which changes will be written. maxChanges The maximum number of changes to return, i.e. the size of the caller's outChanges buffer.

Returns

Common information about the changes contained in outChanges (number of changes, external vs non-external, and the relevant collection)

Releases the memory used by the C4CollectionChange structs (to hold the docID and revID strings.) This must be called after c4dbobs_getChanges().

Note

This function is thread-safe.

Parameters

changes The same array of changes that was passed to c4dbobs_getChanges. numChanges The number of changes returned by c4dbobs_getChanges, i.e. the number of valid items in changes.

Creates a new document observer, with a callback that will be invoked when the document changes.

Note

This function is thread-safe.

Parameters

collection The collection containing the document to observe. docID The ID of the document to observe. callback The function to call after the database changes. context An arbitrary value that will be passed to the callback.

Returns

The new observer reference.

Creates a new query observer, with a callback that will be invoked when the query results change, with an enumerator containing the new results.

Note

This function is thread-safe.

The callback isn't invoked immediately after a change, and won't be invoked after every change, to avoid performance problems. Instead, there's a brief delay so multiple changes can be coalesced.

The new observer needs to be enabled by calling c4queryobs_setEnabled.

Returns the current query results, if any.

When the observer is created, the results are initially NULL until the query finishes running in the background. Once the observer callback is called, the results are available.

Note

This function is thread-safe.

You are responsible for releasing the returned reference.

Parameters

obs The query observer. forget If true, the observer will not hold onto the enumerator, and subsequent calls will return NULL until the next time the observer notifies you. This can help conserve memory, since the query result data will be freed as soon as you release the enumerator. error If the last evaluation of the query failed, the error will be stored here.

Returns

The current query results, or NULL if the query hasn't run or has failed.

Enables a query observer so its callback can be called, or disables it to stop callbacks.

When a query observer is enabled, its callback will be called with the current results. If this is the first observer, the query has to run first (on a background thread) so the callback will take a little while; if there are already enabled observers, the callback will be pretty much instantaneous.

Note

This function is thread-safe if called with enabled being false. Otherwise, the caller must use a lock for Database when this function is called.

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4