opendal/raw/oio/list/
page_list.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18use crate::raw::*;
19use crate::*;
20use std::collections::VecDeque;
21use std::future::Future;
22
23/// PageList is used to implement [`oio::List`] based on API supporting pagination. By implementing
24/// PageList, services don't need to care about the details of page list.
25///
26/// # Architecture
27///
28/// The architecture after adopting [`PageList`]:
29///
30/// - Services impl `PageList`
31/// - `PageLister` impl `List`
32/// - Expose `PageLister` as `Accessor::Lister`
33pub trait PageList: Send + Sync + Unpin + 'static {
34    /// next_page is used to fetch next page of entries from underlying storage.
35    #[cfg(not(target_arch = "wasm32"))]
36    fn next_page(&self, ctx: &mut PageContext) -> impl Future<Output = Result<()>> + MaybeSend;
37    #[cfg(target_arch = "wasm32")]
38    fn next_page(&self, ctx: &mut PageContext) -> impl Future<Output = Result<()>>;
39}
40
41/// PageContext is the context passing between `PageList`.
42///
43/// [`PageLister`] will init the PageContext, and implementer of [`PageList`] should fill the `PageContext`
44/// based on their needs.
45///
46/// - Set `done` to `true` if all page have been fetched.
47/// - Update `token` if there is more page to fetch. `token` is not exposed to users, it's internal used only.
48/// - Push back into the entries for each entry fetched from underlying storage.
49///
50/// NOTE: `entries` is a `VecDeque` to avoid unnecessary memory allocation. Only `push_back` is allowed.
51pub struct PageContext {
52    /// done is used to indicate whether the list operation is done.
53    pub done: bool,
54    /// token is used by underlying storage services to fetch next page.
55    pub token: String,
56    /// entries are used to store entries fetched from underlying storage.
57    ///
58    /// Please always reuse the same `VecDeque` to avoid unnecessary memory allocation.
59    /// PageLister makes sure that entries is reset before calling `next_page`. Implementer
60    /// can call `push_back` on `entries` directly.
61    pub entries: VecDeque<oio::Entry>,
62}
63
64/// PageLister implements [`oio::List`] based on [`PageList`].
65pub struct PageLister<L: PageList> {
66    inner: L,
67    ctx: PageContext,
68}
69
70impl<L> PageLister<L>
71where
72    L: PageList,
73{
74    /// Create a new PageLister.
75    pub fn new(l: L) -> Self {
76        Self {
77            inner: l,
78            ctx: PageContext {
79                done: false,
80                token: "".to_string(),
81                entries: VecDeque::new(),
82            },
83        }
84    }
85}
86
87impl<L> oio::List for PageLister<L>
88where
89    L: PageList,
90{
91    async fn next(&mut self) -> Result<Option<oio::Entry>> {
92        loop {
93            if let Some(entry) = self.ctx.entries.pop_front() {
94                return Ok(Some(entry));
95            }
96            if self.ctx.done {
97                return Ok(None);
98            }
99
100            self.inner.next_page(&mut self.ctx).await?;
101        }
102    }
103}
opendal/raw/oio/list/page_list.rs

opendal/raw/oio/list/
page_list.rs
