Trait kcore::dev::Device

pub trait Device {
    #[must_use]
    fn shutdown<'async_trait>(
        self
    ) -> Result<Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>, AllocError>
    where
        Self: Sized,
        Self: 'async_trait;
    #[must_use]
    fn attach<'life0, 'life1, 'async_trait>(
        &'life0 self, 
        aname: &'life1 [u8]
    ) -> Result<Pin<Box<dyn Future<Output = Result<ChanId>> + Send + 'async_trait>>, AllocError>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        Self: 'async_trait;
    #[must_use]
    fn open<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self, 
        dir: &'life1 ChanId, 
        name: &'life2 [u8], 
        create_dir: Option<bool>
    ) -> Result<Pin<Box<dyn Future<Output = Result<Option<ChanId>>> + Send + 'async_trait>>, AllocError>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,
        Self: 'async_trait;
    #[must_use]
    fn close<'life0, 'async_trait>(
        &'life0 self, 
        c: ChanId
    ) -> Result<Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>, AllocError>
    where
        'life0: 'async_trait,
        Self: 'async_trait;
    #[must_use]
    fn remove<'life0, 'life1, 'async_trait>(
        &'life0 self, 
        c: &'life1 ChanId
    ) -> Result<Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>, AllocError>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        Self: 'async_trait;
    #[must_use]
    fn stat<'life0, 'life1, 'async_trait>(
        &'life0 self, 
        c: &'life1 ChanId
    ) -> Result<Pin<Box<dyn Future<Output = Result<Dirent>> + Send + 'async_trait>>, AllocError>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        Self: 'async_trait;
    #[must_use]
    fn wstat<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self, 
        c: &'life1 ChanId, 
        dirent: &'life2 Dirent
    ) -> Result<Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>, AllocError>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,
        Self: 'async_trait;
    #[must_use]
    fn read<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self, 
        c: &'life1 ChanId, 
        buf: &'life2 mut [u8], 
        off: usize
    ) -> Result<Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>, AllocError>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,
        Self: 'async_trait;
    #[must_use]
    fn write<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self, 
        c: &'life1 ChanId, 
        buf: &'life2 [u8], 
        off: usize
    ) -> Result<Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>, AllocError>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,
        Self: 'async_trait;
    #[must_use]
    fn truncate<'life0, 'life1, 'async_trait>(
        &'life0 self, 
        c: &'life1 ChanId, 
        size: usize
    ) -> Result<Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>, AllocError>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        Self: 'async_trait;
}

Common trait of a device driver.

Why not use GAT to get async trait?

Since that may cause loop when our FS is dependent on a Chan, and the compiler cannot determine the future size at compile time. Think of the case when we have FS on a file, which resides on another FS, and the length of such chain cannot be known at compile time.

Required methods

#[must_use]

fn shutdown<'async_trait>(
    self
) -> Result<Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>, AllocError> where
    Self: Sized,
    Self: 'async_trait, 

The async destructor of the device.

This may be called when some device in the global device table Vec<Arc> has no reference(i.e. no opened file).

#[must_use]

fn attach<'life0, 'life1, 'async_trait>(
    &'life0 self,
    aname: &'life1 [u8]
) -> Result<Pin<Box<dyn Future<Output = Result<ChanId>> + Send + 'async_trait>>, AllocError> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: 'async_trait, 

Return the root channel. aname is a user-specified hint.

#[must_use]

fn open<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    dir: &'life1 ChanId,
    name: &'life2 [u8],
    create_dir: Option<bool>
) -> Result<Pin<Box<dyn Future<Output = Result<Option<ChanId>>> + Send + 'async_trait>>, AllocError> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    Self: 'async_trait, 

Open a file in the directory or reopen a file.

If name is empty, ignore other parameters and reopen the file itself(same as dup). The reopen operation returns either an error or some chan id(but not None).

dir is guaranteed to be a directory if name is not empty.

If create_dir is None, this operation is a normal open. Return None if not found.

Otherwise, it means creating a file. The boolean indicates type of the file to be created is a directory or not. Return None if the file already exist.

#[must_use]

fn close<'life0, 'async_trait>(
    &'life0 self,
    c: ChanId
) -> Result<Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>, AllocError> where
    'life0: 'async_trait,
    Self: 'async_trait, 

Close a file. The drop of channel is done by Chan::close

This function must always succeed.

#[must_use]

fn remove<'life0, 'life1, 'async_trait>(
    &'life0 self,
    c: &'life1 ChanId
) -> Result<Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>, AllocError> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: 'async_trait, 

Remove a file by hint such that the server won’t remove the file until all clients have closed it. Can only remove normal file or empty directory. May not atomic since having to truncate the file first.

Return true if removed, else false.

#[must_use]

fn stat<'life0, 'life1, 'async_trait>(
    &'life0 self,
    c: &'life1 ChanId
) -> Result<Pin<Box<dyn Future<Output = Result<Dirent>> + Send + 'async_trait>>, AllocError> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: 'async_trait, 

Inquires about the file attribute identified by a channel.

#[must_use]

fn wstat<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    c: &'life1 ChanId,
    dirent: &'life2 Dirent
) -> Result<Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>, AllocError> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    Self: 'async_trait, 

Change the file attribute identified by a channel. Should be atomic.

#[must_use]

fn read<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    c: &'life1 ChanId,
    buf: &'life2 mut [u8],
    off: usize
) -> Result<Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>, AllocError> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    Self: 'async_trait, 

Read data from a channel by offset and store to buffer.

For plain files, it returns the number of bytes read.

For directories, read returns an integral number of directory entries exactly as in stat, one for each member of the directory. The offset and buffer len must be zero modulo DIRLEN.

#[must_use]

fn write<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    c: &'life1 ChanId,
    buf: &'life2 [u8],
    off: usize
) -> Result<Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>, AllocError> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    Self: 'async_trait, 

Write the data in buffer to a channel starting by specific offset. Directories are not allowed to be written.

Return the number of bytes writed.

#[must_use]

fn truncate<'life0, 'life1, 'async_trait>(
    &'life0 self,
    c: &'life1 ChanId,
    size: usize
) -> Result<Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>, AllocError> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: 'async_trait, 

Reduce the size of a file.

If the file previously was larger than or equal to this size, the extra data is lost. Otherwise, do nothing.

Return the new size, which may or may not be equal to the expected size.

NOTE: truncate with infinite size can be used to retrieve the size of the file. Why not resize? Since resize by write can better handle initial bytes.

Implementors