[skywalking-banyandb] branch main updated: Supply Persistence Storage doc (#292)

[ha...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

hanahmily pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-banyandb.git


The following commit(s) were added to refs/heads/main by this push:
     new 3c3ef3c4 Supply Persistence Storage doc (#292)
3c3ef3c4 is described below

commit 3c3ef3c4801f017b65a42ccb680d2777db656172
Author: HHoflittlefish777 <77...@users.noreply.github.com>
AuthorDate: Thu Jul 13 21:54:14 2023 +0800

    Supply Persistence Storage doc (#292)
    
    * supply Persistence Storage doc
    
    ---------
    
    Co-authored-by: Gao Hongtao <ha...@gmail.com>
---
 assets/io_uring.jpg                 | Bin 0 -> 107392 bytes
 docs/concept/persistence-storage.md | 155 +++++++++++++++++++++++++++++++++---
 2 files changed, 145 insertions(+), 10 deletions(-)

diff --git a/assets/io_uring.jpg b/assets/io_uring.jpg
new file mode 100644
index 00000000..c3e792fd
Binary files /dev/null and b/assets/io_uring.jpg differ
diff --git a/docs/concept/persistence-storage.md b/docs/concept/persistence-storage.md
index e14605bf..ca330a90 100644
--- a/docs/concept/persistence-storage.md
+++ b/docs/concept/persistence-storage.md
@@ -3,10 +3,12 @@ Persistence storage is used for unifying data of BanyanDB persistence, including
 BanyanDB provides a concise interface that shields the complexity of the implementation from the upper layer. By exposing necessary interfaces, upper components do not need to care how persistence is implemented and avoid dealing with differences between different operating systems.
 
 # IO Mode
-Persistence storage offers a range of IO modes to cater to various throughput requirements. The interface can be accessed by developers and can be configured through settings.
+Persistence storage offers a range of IO modes to cater to various throughput requirements. The interface can be accessed by developers and can be configured through settings, which can be set in the configuration file.
 
 ## Io_uring
-Io_uring is a new feature in Linux 5.1, which is fully asynchronous and offers high throughput. In the scene of massive storage, io_uring can bring significant benefits.
+Io_uring is a new feature in Linux 5.1, which is fully asynchronous and offers high throughput. In the scene of massive storage, io_uring can bring significant benefits. The following is the diagram about how io_uring works.
+![](/assets/io_uring.jpg)
+If the user sets io_uring for use, the read and write requests will first be placed in the submission queue buffer when calling the operation API. When the threshold is reached, batch submissions will be made to SQ. After the kernel threads complete execution, the requests will be placed in the CQ, and the user can obtain the request results.
 
 ## Synchronous IO
 The most common IO mode is Synchronous IO, but it has a relatively low throughput. BanyanDB provides a nonblocking mode that is compatible with lower Linux versions.
@@ -14,41 +16,174 @@ The most common IO mode is Synchronous IO, but it has a relatively low throughpu
 # Operation
 ## Directory
 ### Create
-Create the specified directory and return an error if the directory already exists.
+Create the specified directory and return the file descriptor, the error will happen if the directory already exists.
+The following is the pseudocode that calls the API in the go style.、
+
+param:
+
+name: The name of the directory.
+
+permisson: Permission you want to set. BanyanDB provides three modes: Read, Write, ReadAndWrite. you can use it as Mode.Read.
+
+`CreateDirectory(name String, permission Mode) (error)`
+
+### Open
+Open the directory and return an error if the file descriptor does not exist.
+The following is the pseudocode that calls the API in the go style.
+
+param:
+
+name: The name of the directory.
+
+return: Directory pointer, you can use it for various operations.
+
+`OpenDirectory(name String) (*Dir, error)`
 
 ### Delete
 Delete the directory and all files and return an error if the directory does not exist or the directory not reading or writing.
+The following is the pseudocode that calls the API in the go style.
+
+`Dir.DeleteDirectory() (error)`
 
 ### Rename
 Rename the directory and return an error if the directory already exists.
+The following is the pseudocode that calls the API in the go style.
+
+param:
+
+name: The name of the directory.
+
+`Dir.RenameDirectory(newName String) (error)`
+
+### Read
+Get all lists of files or children's directories in the directory and an error if the directory does not exist.
+The following is the pseudocode that calls the API in the go style.
 
-### Get Children
-Get all lists of files or children's directories in the directory and return an error if the directory does not exist.
+return: List of files belonging to the directory.
+
+`Dir.ReadDirectory() (FileList, error)`
 
 ### Permission
 When creating a file, the default owner is the user who created the directory. The owner can specify read and write permissions of the directory. If not specified, the default is read and write permissions, which include permissions for all files in the directory.
+The following is the pseudocode that calls the API in the go style.
+
+param:
+
+permisson: Permission you want to set. BanyanDB provides three mode: Read, Write, ReadAndWrite. you can use it as Mode.Read.
+
+`Dir.SetDirectoryPermission(permission Mode) (error)`
 
 ## File
+### Create
+Create the specified file and return the file descriptor, the error will happen if the file already exists.
+The following is the pseudocode that calls the API in the go style.
+
+param:
+    
+name: The name of the file.
+
+permisson: Permission you want to set. BanyanDB provides three mode: Read, Write, ReadAndWrite. you can use it as Mode.Read.
+
+`CreateFile(name String, permission Mode) (error)`
+
+### Open
+Open the file and return an error if the file descriptor does not exist.
+The following is the pseudocode that calls the API in the go style.
+
+param:
+
+name: The name of the file.
+
+return: File pointer, you can use it for various operations.
+
+`OpenFile(name String) (*File, error)`
+
 ### Write
 BanyanDB provides two methods for writing files.
 Append mode, which adds new data to the end of a file. This mode is typically used for WAL.
-Flush mode, which flushes all data to one or more files and can specify the size of each file to write to.
-It will return an error when writing a directory, the file does not exist or there is not enough space, and the incomplete file will be discarded.
+Flush mode, which flushes all data to one file. It will return an error when writing a directory, the file does not exist or there is not enough space, and the incomplete file will be discarded. The flush operation is atomic, which means the file won't be created if an error happens during the flush process.
+The following is the pseudocode that calls the API in the go style.
+
+For append mode:
+
+param:
+
+buffer: The data append to the file.
+
+`File.AppendWriteFile(buffer []byte) (error)`
+
+For flush mode:
+
+param:
+
+buffer: The data append to the file.
+
+permisson: Permission you want to set. BanyanDB provides three mode: Read, Write, ReadAndWrite. you can use it as Mode.Read.
+
+return: File pointer, you can use it for various operations.
+
+`FlushWriteFile(buffer []byte, permission Mode) (*File, error)`
 
 ### Delete
-BanyanDB provides a batch-deleting operation, which can delete several files at once. it will return an error if the directory does not exist or the file not reading or writing.
+BanyanDB provides the deleting operation, which can delete a file at once. it will return an error if the directory does not exist or the file not reading or writing.
+
+The following is the pseudocode that calls the API in the go style.
+
+`File.DeleteFile() (error)`
 
 ### Read
 For reading operation, two read methods are provided:
 Reading a specified location of data, which relies on a specified offset and a buffer.
 Read the entire file, BanyanDB provides stream reading, which can use when the file is too large, the size gets each time can be set when using stream reading.
 If entering incorrect parameters such as incorrect offset or non-existent file, it will return an error.
+The following is the pseudocode that calls the API in the go style.
+
+For reading specified location of data:
+
+param:
+
+offset: Read begin location of the file.
+
+buffer: The read length is the same as the buffer length.
+
+`File.ReadFile(offset int, buffer []byte) (error)`
+
+For stream reading:
+
+param:
+
+offset: Read begin location of the file.
+
+buffer: Every read length in the stream is the same as the buffer length.
+
+return: A Iterator, the size of each iteration is the length of the buffer.
+
+`File.StreamReadFile(offset int, buffer []byte) (*iter, error)`
 
 ### Rename
 Rename the file and return an error if the directory exists in this directory.
+The following is the pseudocode that calls the API in the go style.
+
+param:
+
+newName: The new name of the file.
+
+`File.RenameFile(newName String) (error)`
 
 ### Get size
-Get the file size and return an error if the file does not exist.
+Get the file written data's size and return an error if the file does not exist. The unit of file size is Byte.
+The following is the pseudocode that calls the API in the go style.
+
+return: the file written data's size.
+
+`File.GetFileSize() (int, error)`
 
 ### Permission
-When creating a file, the default owner is the user who created the file. The owner can specify the read and write permissions of the file. If not specified, the default is read and write permissions.
\ No newline at end of file
+When creating a file, the default owner is the user who created the file. The owner can specify the read and write permissions of the file. If not specified, the default is read and write permissions.
+The following is the pseudocode that calls the API in the go style.
+
+param:
+
+permisson: Permission you want to set. BanyanDB provides three mode: Read, Write, ReadAndWrite. you can use it as Mode.Read.
+
+`File.SetFilePermission(permission Mode) (error)`