opendal/raw/oio/write/
api.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::future::Future;
19use std::ops::DerefMut;
20
21use crate::raw::*;
22use crate::*;
23
24/// Writer is a type erased [`Write`]
25pub type Writer = Box<dyn WriteDyn>;
26
27/// Write is the trait that OpenDAL returns to callers.
28pub trait Write: Unpin + Send + Sync {
29    /// Write given bytes into writer.
30    ///
31    /// # Behavior
32    ///
33    /// - `Ok(())` means all bytes has been written successfully.
34    /// - `Err(err)` means error happens and no bytes has been written.
35    fn write(&mut self, bs: Buffer) -> impl Future<Output = Result<()>> + MaybeSend;
36
37    /// Close the writer and make sure all data has been flushed.
38    fn close(&mut self) -> impl Future<Output = Result<Metadata>> + MaybeSend;
39
40    /// Abort the pending writer.
41    fn abort(&mut self) -> impl Future<Output = Result<()>> + MaybeSend;
42}
43
44impl Write for () {
45    async fn write(&mut self, _: Buffer) -> Result<()> {
46        unimplemented!("write is required to be implemented for oio::Write")
47    }
48
49    async fn close(&mut self) -> Result<Metadata> {
50        Err(Error::new(
51            ErrorKind::Unsupported,
52            "output writer doesn't support close",
53        ))
54    }
55
56    async fn abort(&mut self) -> Result<()> {
57        Err(Error::new(
58            ErrorKind::Unsupported,
59            "output writer doesn't support abort",
60        ))
61    }
62}
63
64pub trait WriteDyn: Unpin + Send + Sync {
65    fn write_dyn(&mut self, bs: Buffer) -> BoxedFuture<Result<()>>;
66
67    fn close_dyn(&mut self) -> BoxedFuture<Result<Metadata>>;
68
69    fn abort_dyn(&mut self) -> BoxedFuture<Result<()>>;
70}
71
72impl<T: Write + ?Sized> WriteDyn for T {
73    fn write_dyn(&mut self, bs: Buffer) -> BoxedFuture<Result<()>> {
74        Box::pin(self.write(bs))
75    }
76
77    fn close_dyn(&mut self) -> BoxedFuture<Result<Metadata>> {
78        Box::pin(self.close())
79    }
80
81    fn abort_dyn(&mut self) -> BoxedFuture<Result<()>> {
82        Box::pin(self.abort())
83    }
84}
85
86impl<T: WriteDyn + ?Sized> Write for Box<T> {
87    async fn write(&mut self, bs: Buffer) -> Result<()> {
88        self.deref_mut().write_dyn(bs).await
89    }
90
91    async fn close(&mut self) -> Result<Metadata> {
92        self.deref_mut().close_dyn().await
93    }
94
95    async fn abort(&mut self) -> Result<()> {
96        self.deref_mut().abort_dyn().await
97    }
98}
99
100/// BlockingWriter is a type erased [`BlockingWrite`]
101pub type BlockingWriter = Box<dyn BlockingWrite>;
102
103/// BlockingWrite is the trait that OpenDAL returns to callers.
104pub trait BlockingWrite: Send + Sync + 'static {
105    /// Write whole content at once.
106    ///
107    /// # Behavior
108    ///
109    /// - `Ok(n)` means `n` bytes has been written successfully.
110    /// - `Err(err)` means error happens and no bytes has been written.
111    ///
112    /// It's possible that `n < bs.len()`, caller should pass the remaining bytes
113    /// repeatedly until all bytes has been written.
114    fn write(&mut self, bs: Buffer) -> Result<()>;
115
116    /// Close the writer and make sure all data has been flushed.
117    fn close(&mut self) -> Result<Metadata>;
118}
119
120impl BlockingWrite for () {
121    fn write(&mut self, bs: Buffer) -> Result<()> {
122        let _ = bs;
123
124        unimplemented!("write is required to be implemented for oio::BlockingWrite")
125    }
126
127    fn close(&mut self) -> Result<Metadata> {
128        Err(Error::new(
129            ErrorKind::Unsupported,
130            "output writer doesn't support close",
131        ))
132    }
133}
134
135/// `Box<dyn BlockingWrite>` won't implement `BlockingWrite` automatically.
136///
137/// To make BlockingWriter work as expected, we must add this impl.
138impl<T: BlockingWrite + ?Sized> BlockingWrite for Box<T> {
139    fn write(&mut self, bs: Buffer) -> Result<()> {
140        (**self).write(bs)
141    }
142
143    fn close(&mut self) -> Result<Metadata> {
144        (**self).close()
145    }
146}
opendal/raw/oio/write/api.rs

opendal/raw/oio/write/
api.rs
