github.com/iceber/iouring-go@v0.0.0-20230403020409-002cfd2e2a90/README.md (about)

     1  # What is io_uring
     2  [io_uring](http://kernel.dk/io_uring.pdf) 
     3  
     4  [io_uring-wahtsnew](https://kernel.dk/io_uring-whatsnew.pdf) 
     5  
     6  [LWN io_uring](https://lwn.net/Kernel/Index/#io_uring) 
     7  
     8  [Lord of the io_uring](https://unixism.net/loti/)
     9  
    10  [【译】高性能异步 IO —— io_uring (Effecient IO with io_uring)](http://icebergu.com/archives/linux-iouring)
    11  
    12  [Go 与异步 IO - io_uring 的思考](http://icebergu.com/archives/go-iouring)
    13  
    14  # Features
    15  - [x] register a file set for io_uring instance
    16  - [x] support file IO
    17  - [x] support socket IO
    18  - [x] support IO timeout
    19  - [x] link request
    20  - [x] set timer
    21  - [x] add request extra info, could get it from the result
    22  - [ ] set logger
    23  - [ ] register buffers and IO with buffers
    24  - [ ] support SQPoll 
    25  
    26  # OS Requirements
    27  * Linux Kernel >= 5.6
    28  
    29  
    30  # Installation
    31  ```
    32  go get github.com/iceber/iouring-go
    33  ```
    34  [doc](https://pkg.go.dev/github.com/iceber/iouring-go)
    35  
    36  # Quickstart
    37  ```golang
    38  package main
    39  
    40  import (
    41          "fmt"
    42          "os"
    43  
    44          "github.com/iceber/iouring-go"
    45  )
    46  
    47  var str = "io with iouring"
    48  
    49  func main() {
    50          iour, err := iouring.New(1)
    51          if err != nil {
    52                  panic(fmt.Sprintf("new IOURing error: %v", err))
    53          }
    54          defer iour.Close()
    55  
    56          file, err := os.Create("./tmp.txt")
    57          if err != nil {
    58                  panic(err)
    59          }
    60  
    61          ch := make(chan iouring.Result, 1)
    62  
    63          prepRequest := iouring.Write(int(file.Fd()), []byte(str))
    64          if _, err := iour.SubmitRequest(prepRequest, ch); err != nil {
    65                  panic(err)
    66          }
    67  
    68          result := <-ch
    69          i, err := result.ReturnInt()
    70          if err != nil {
    71                  fmt.Println("write error: ", err)
    72                  return
    73          }
    74  
    75          fmt.Printf("write byte: %d\n", i)
    76  }
    77  ```
    78  
    79  # Request With Extra Info
    80  ```golang
    81  prepRequest := iouring.Write(int(file.Fd()), []byte(str)).WithInfo(file.Name())
    82  
    83  request, err := iour.SubmitRequest(prepRequest, nil)
    84  if err != nil {
    85      panic(err)
    86  }
    87  
    88  <- request.Done()
    89  info, ok := request.GetRequestInfo().(string)
    90  ```
    91  
    92  # Cancel Request
    93  ```golang
    94  prepR := iouring.Timeout(5 * time.Second)
    95  request, err := iour.SubmitRequest(prepR, nil)
    96  if err != nil {
    97      panic(err)
    98  }
    99  
   100  if _, err := request.Cancel(); err != nil{
   101      fmt.Printf("cancel request error: %v\n", err)
   102      return
   103  }
   104  
   105  <- request.Done()
   106  if err := request.Err(); err != nil{
   107      if err == iouring.ErrRequestCanceled{
   108          fmt.Println("request is canceled"0
   109          return
   110      }
   111      fmt.Printf("request error: %v\n", err)
   112      return
   113  }
   114  ```
   115  
   116  
   117  # Submit multitude request
   118  
   119  ```golang
   120  var offset uint64
   121  buf1 := make([]byte, 1024)
   122  prep1:= iouring.Pread(fd, buf1, offset)
   123  
   124  offset += 1024
   125  buf2 := make([]byte, 1024)
   126  prep2:= iouring.Pread(fd, buf1, offset)
   127  
   128  requests, err := iour.SubmitRequests([]iouring.PrepRequest{prep1,prep2}, nil)
   129  if err != nil{
   130      panic(err)
   131  }
   132  <- requests.Done()
   133  fmt.Println("requests are completed")
   134  ```
   135  requests is concurrent execution
   136  
   137  # Link request
   138  ```golang
   139  var offset uint64
   140  buf := make([]byte, 1024)
   141  prep1 := iouring.Pread(fd, buf1, offset)
   142  prep2 := iouring.Write(int(os.Stdout.Fd()), buf)
   143  
   144  iour.SubmitLinkRequests([]iouring.PrepRequest{prep1, prep2}, nil)
   145  ```
   146  
   147  # Examples
   148  [cat](https://github.com/Iceber/iouring-go/tree/main/examples/cat)
   149  
   150  [concurrent-cat](https://github.com/Iceber/iouring-go/tree/main/examples/concurrent-cat)
   151  
   152  [cp](https://github.com/Iceber/iouring-go/tree/main/examples/cp)
   153  
   154  [request-with-timeout](https://github.com/Iceber/iouring-go/tree/main/examples/timeout/request-with-timeout)
   155  
   156  [link-request](https://github.com/Iceber/iouring-go/tree/main/examples/link)
   157  
   158  [link-with-timeout](https://github.com/Iceber/iouring-go/tree/main/examples/timeout/link-with-timeout)
   159  
   160  [timer](https://github.com/Iceber/iouring-go/tree/main/examples/timeout/timer)
   161  
   162  [echo](https://github.com/Iceber/iouring-go/tree/main/examples/echo)
   163  
   164  [echo-with-callback](https://github.com/Iceber/iouring-go/tree/main/examples/echo-with-callback)
   165  
   166  # TODO
   167  * add tests
   168  * arguments type (eg. int and int32)
   169  * set logger