1# readahead
2Asynchronous read-ahead for Go readers
3
4This package will allow you to add readhead to any reader. This means a separate goroutine will perform reads from your upstream reader, so you can request from this reader without delay.
5
6This is helpful for splitting an input stream into concurrent processing, and also helps smooth out **bursts** of input or output.
7
8This should be fully transparent, except that once an error has been returned from the Reader, it will not recover. A panic will be caught and returned as an error.
9
10The readahead object also fulfills the [`io.WriterTo`](https://golang.org/pkg/io/#WriterTo) interface, which is likely to speed up `io.Copy` and other code that use the interface.
11
12See an introduction: [An Async Read-ahead Package for Go](https://blog.klauspost.com/an-async-read-ahead-package-for-go/)
13
14[![GoDoc][1]][2] [![Build Status][3]][4]
15
16[1]: https://godoc.org/github.com/klauspost/readahead?status.svg
17[2]: https://godoc.org/github.com/klauspost/readahead
18[3]: https://travis-ci.org/klauspost/readahead.svg
19[4]: https://travis-ci.org/klauspost/readahead
20
21# usage
22
23To get the package use `go get -u github.com/klauspost/readahead`.
24
25Here is a simple example that does file copy. Error handling has been omitted for brevity.
26```Go
27input, _ := os.Open("input.txt")
28output, _ := os.Create("output.txt")
29defer input.Close()
30defer output.Close()
31
32// Create a read-ahead Reader with default settings
33ra := readahead.NewReader(input)
34defer ra.Close()
35
36// Copy the content to our output
37_, _ = io.Copy(output, ra)
38```
39
40# settings
41
42You can finetune the read-ahead for your specific use case, and adjust the number of buffers and the size of each buffer.
43
44The default the size of each buffer is 1MB, and there are 4 buffers. Do not make your buffers too small since there is a small overhead for passing buffers between goroutines. Other than that you are free to experiment with buffer sizes.
45
46# contributions
47
48On this project contributions in terms of new features is limited to:
49
50* Features that are widely usable and
51* Features that have extensive tests
52
53This package is meant to be simple and stable, so therefore these strict requirements.
54
55# license
56
57This package is released under the MIT license. See the supplied LICENSE file for more info.
View as plain text