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 std::collections::VecDeque;
19use std::future::Future;
20
21use crate::raw::*;
22use crate::*;
23
24/// PageList is used to implement [`oio::List`] based on API supporting pagination. By implementing
25/// PageList, services don't need to care about the details of page list.
26///
27/// # Architecture
28///
29/// The architecture after adopting [`PageList`]:
30///
31/// - Services impl `PageList`
32/// - `PageLister` impl `List`
33/// - Expose `PageLister` as `Accessor::Lister`
34pub trait PageList: Send + Sync + Unpin + 'static {
35 /// next_page is used to fetch next page of entries from underlying storage.
36 #[cfg(not(target_arch = "wasm32"))]
37 fn next_page(&self, ctx: &mut PageContext) -> impl Future<Output = Result<()>> + MaybeSend;
38 #[cfg(target_arch = "wasm32")]
39 fn next_page(&self, ctx: &mut PageContext) -> impl Future<Output = Result<()>>;
40}
41
42/// PageContext is the context passing between `PageList`.
43///
44/// [`PageLister`] will init the PageContext, and implementer of [`PageList`] should fill the `PageContext`
45/// based on their needs.
46///
47/// - Set `done` to `true` if all page have been fetched.
48/// - Update `token` if there is more page to fetch. `token` is not exposed to users, it's internal used only.
49/// - Push back into the entries for each entry fetched from underlying storage.
50///
51/// NOTE: `entries` is a `VecDeque` to avoid unnecessary memory allocation. Only `push_back` is allowed.
52pub struct PageContext {
53 /// done is used to indicate whether the list operation is done.
54 pub done: bool,
55 /// token is used by underlying storage services to fetch next page.
56 pub token: String,
57 /// entries are used to store entries fetched from underlying storage.
58 ///
59 /// Please always reuse the same `VecDeque` to avoid unnecessary memory allocation.
60 /// PageLister makes sure that entries is reset before calling `next_page`. Implementer
61 /// can call `push_back` on `entries` directly.
62 pub entries: VecDeque<oio::Entry>,
63}
64
65/// PageLister implements [`oio::List`] based on [`PageList`].
66pub struct PageLister<L: PageList> {
67 inner: L,
68 ctx: PageContext,
69}
70
71impl<L> PageLister<L>
72where
73 L: PageList,
74{
75 /// Create a new PageLister.
76 pub fn new(l: L) -> Self {
77 Self {
78 inner: l,
79 ctx: PageContext {
80 done: false,
81 token: "".to_string(),
82 entries: VecDeque::new(),
83 },
84 }
85 }
86}
87
88impl<L> oio::List for PageLister<L>
89where
90 L: PageList,
91{
92 async fn next(&mut self) -> Result<Option<oio::Entry>> {
93 loop {
94 if let Some(entry) = self.ctx.entries.pop_front() {
95 return Ok(Some(entry));
96 }
97 if self.ctx.done {
98 return Ok(None);
99 }
100
101 self.inner.next_page(&mut self.ctx).await?;
102 }
103 }
104}