Struct RoomPagination

pub struct RoomPagination { /* private fields */ }

An API object to run pagination queries on a super::RoomEventCache.

Can be created with super::RoomEventCache::pagination().

Implementations

impl RoomPagination

pub async fn run_backwards<Until, Break, UntilFuture>( &self, batch_size: u16, until: Until, ) -> Result<Break>

where Until: FnMut(BackPaginationOutcome, TimelineHasBeenResetWhilePaginating) -> UntilFuture, UntilFuture: Future<Output = ControlFlow<Break, ()>>,

Starts a back-pagination for the requested number of events.

This automatically takes care of waiting for a pagination token from sync, if we haven’t done that before.

The until argument is an async closure that returns a ControlFlow to decide whether a new pagination must be run or not. It’s helpful when the server replies with e.g. a certain set of events, but we would like more, or the event we are looking for isn’t part of this set: in this case, until returns ControlFlow::Continue, otherwise it returns ControlFlow::Break. until receives BackPaginationOutcome as its sole argument.

Errors

It may return an error if the pagination token used during back-pagination has disappeared while we started the pagination. In that case, it’s desirable to call the method again.

Example

To do a single run:

use std::ops::ControlFlow;

use matrix_sdk::event_cache::{
    BackPaginationOutcome,
    RoomPagination,
    TimelineHasBeenResetWhilePaginating
};

let result = room_pagination.run_backwards(
    42,
    |BackPaginationOutcome { events, reached_start },
     _timeline_has_been_reset: TimelineHasBeenResetWhilePaginating| async move {
        // Do something with `events` and `reached_start` maybe?
        let _ = events;
        let _ = reached_start;

        ControlFlow::Break(())
    }
).await;

pub fn status(&self) -> Subscriber<PaginatorState>

Returns a subscriber to the pagination status used for the back-pagination integrated to the event cache.

pub fn hit_timeline_start(&self) -> bool

Returns whether we’ve hit the start of the timeline.

This is true if, and only if, we didn’t have a previous-batch token and running backwards pagination would be useless.

pub fn hit_timeline_end(&self) -> bool

Returns whether we’ve hit the end of the timeline.

This is true if, and only if, we didn’t have a next-batch token and running forwards pagination would be useless.