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