README
¶
ctxfs
Package ctxfs provides Context-aware file system access.
That is, File system package that supports cancellation via Context, and is aware of active file descriptor limits.
Documentation
¶
Overview ¶
Package ctxfs provides Context-aware file system access.
A file is typically opened with Open or Create. The File object can provide io.Reader and io.Writer views on the file bound to a context using the IO method. For example to read a file:
ctx := context.WithTimeout(context.Background(), 1*time.Second)
f, err := fs.Open("file.go")
if err != nil {
log.Fatal(err)
}
b, err := ioutil.ReadAll(f.IO(ctx))
if err != nil {
log.Fatal(err)
}
Interrupting the underlying system calls is implemented using operating system signals. This package uses SIGUSR1, programs that use this package should avoid using that signal to minimize the performance penalty.
There are several known conditions where blocking system calls cannot be interrupted even by non-restartable signals. In those cases, canceling a context will not work. Examples include:
- darwin will not interrupt a partially successful write to a pipe
- linux will not interrupt normal disk I/O (see SA_RESTART in signal(7)).
As cancellation of contexts should be treated as advisory, it is best to program with the expectation that some calls will not be cleaned up promptly. If this is not possible, calling the SetNonBlocking method on a File object will enable non-blocking I/O. The contract of the io.Reader and io.Writer interfaces will be met, though at a potential performance penalty.
TODO: document and implement OpenLimit.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var OpenLimit int
OpenLimit is the maximum number of file descriptors that can be open simultaneously by the fs package.
Initial value is 10% less than RLIMIT_NOFILE at process initialization.
Functions ¶
This section is empty.
Types ¶
type File ¶
type File struct {
// contains filtered or unexported fields
}
File holds an open file descriptor.
func Open ¶
Open opens the named file for reading.
If the number of opened files exceeds OpenLimit, Open will block until another file is closed.
If there is an error, it will be of type *PathError.
func OpenFile ¶
OpenFile is the generalized open call; most users will use Open or Create instead.
If the number of open files exceeds OpenLimit, Open will block until another file is closed.
If there is an error, it will be of type *os.PathError.
func (*File) IO ¶
IO returns an IO object bound to ctx for all of its operations.
The underlying file descriptor is shared with File. IO can be called multiple times with different ctx values.
func (*File) SetNonBlocking ¶
func (f *File) SetNonBlocking()
SetNonBlocking puts the underlying file descriptor into non-blocking mode. This is equivalent to O_NONBLOCK.
Source Files