Unity Scopes API
|
Base class for a client to receive and buffer the results of a query until another BufferedResultForwarder becomes ready. More...
Public Member Functions | |
BufferedResultForwarder (unity::scopes::SearchReplyProxy const &upstream, BufferedResultForwarder::SPtr const &next_forwarder=BufferedResultForwarder::SPtr()) | |
Create a forwarder that sends (at least one) result to its upstream reply proxy before indicating that it is ready to its follower. More... | |
void | push (CategorisedResult result) override |
Forwards a single result before calling set_ready() . More... | |
bool | is_ready () const |
Check if this forwarder is ready. More... | |
![]() | |
virtual void | push (Department::SCPtr const &parent) |
Called at most once by the scopes run time for a tree of departments returned by a query. More... | |
virtual void | push (experimental::Annotation annotation) |
Called once by the scopes run time for each annotation that is returned by a query(). More... | |
virtual void | push (Category::SCPtr const &category) |
Called once by the scopes run time for each category that is returned by a query(). More... | |
virtual void | push (Filters const &filters, FilterState const &filter_state) |
Called once by the scopes to send all the filters and their state. More... | |
![]() | |
virtual void | info (OperationInfo const &op_info) |
Called by the scopes run time each time a scope reports additional information about the reply to a query. More... | |
Protected Member Functions | |
void | set_ready () |
Mark this forwarder as ready. More... | |
unity::scopes::SearchReplyProxy | upstream () const |
Get the upstream proxy. More... | |
void | finished (CompletionDetails const &details) override |
Called once by the scopes run time after the final result for a request was sent. More... | |
Base class for a client to receive and buffer the results of a query until another BufferedResultForwarder becomes ready.
This class implements result buffering, useful for aggregator scopes that receive results from multiple child scopes and need to display categories in a specific order. The aggregator scope must create an instance of BufferedResultForwarder for every child scope it queries and chain the instances together in the desired order.
The default implementation of BufferedResultForwarder forwards the results it receives upstream and declares itself "ready" after receiving the first result. The results are then buffered until all prior forwarders have declared themselves ready. Buffering is very efficient—results are buffered only until proper order is guaranteed, and buffering is disabled for forwarders that do not need to wait for a predecessor to become ready. This means that results are pushed to the client (displayed) as early as possible.
The default implementation only pushes results and their categories, but ignores departments, filters, and annotations. If you wish to handle and forward these, you must to derive your own forwarder from BufferedResultForwarder and override the appropropriate methods of the SearchListenerBase class.
The default implementation buffers a single result before indicating to its follower that it is ready. This means that the first category from each child determines overall order. For example, if each child produces results for a single category, the chaining insures the correct order (results from child A followed by results from child B, or vice versa). However, if child A produces results for categories A1 and A2, and child B produces results for categories B1 and B2, the overall order could, for example, be A1, B1, A2, B2, or it could be A1, A2, B1, B2, or it could be A1, B2, B1, A2 (among others).
If you want to ensure that all categories from child A arrive in a particular order, followed by all categories from child B in a particular order, you must override push() to, for example, collapse categories received from a child into a single category, or otherwise buffer results yourself until you have established the order you need.
Note that buffering fundamentally conflicts with the need to render results as soon as possible. You should avoid buffering more data than absolutely necessary in order for the display to start updating as soon as possible after a query was sent.
If you create a custom implementation of a forwarder, you must push results via the proxy returned by BufferedResultForwarder::upstream(). (This is a different proxy than the one that is passed to the constructor.) Your forwarder then must declare itself ready by calling BufferedResultForwarder::set_ready() as soon as it knows it will not push results for any new categories. In the case where your aggregator aggregates all results from given child scope into a single category, you can call set_ready()
as soon as you have pushed the first result.
Here is a code example that shows how to write a result forwarder that creates a separate category for results from each of three children and controls the order in which these categories are rendered.
unity::scopes::utility::BufferedResultForwarder::BufferedResultForwarder | ( | unity::scopes::SearchReplyProxy const & | upstream, |
BufferedResultForwarder::SPtr const & | next_forwarder = BufferedResultForwarder::SPtr() |
||
) |
Create a forwarder that sends (at least one) result to its upstream reply proxy before indicating that it is ready to its follower.
upstream | The reply proxy for the upstream receiver. |
next_forwarder | The forwarder that becomes ready once this forwarder calls set_ready(). |
unity::LogicException | when passed next_forwarder that has already been linked to another BufferedResultForwarder. |
|
overrideprotectedvirtual |
Called once by the scopes run time after the final result for a request was sent.
Calls to finished() are made by an arbitrary thread.
Exceptions thrown from finished() are ignored.
details | Contains details about the completion status of a query as well as any additional information regarding the operation of the request. |
Implements unity::scopes::ListenerBase.
bool unity::scopes::utility::BufferedResultForwarder::is_ready | ( | ) | const |
Check if this forwarder is ready.
Once ready, the forwarder no longer buffers any results and passes them to the upstream proxy immediately.
true
if this forwarder called set_ready(), false
otherwise.
|
overridevirtual |
Forwards a single result before calling set_ready()
.
This default implementation forwards incoming results unchanged to the upstream reply proxy and marks the forwarder ready after forwarding the first result.
This method is called once by the scopes run time for each result that is returned by a query().
result | The received result. |
Implements unity::scopes::SearchListenerBase.
|
protected |
Mark this forwarder as ready.
If you create a custom forwarder, you should call this method as soon as your forwarder will no longer push results for new categories.
|
protected |
Get the upstream proxy.
Returns an instance of buffered reply proxy for all push, register_departments, and register_category operations. Note that this proxy is not the same proxy as the one passed to the constructor.