Debian Codegraph @

io/handle.ha

raw
1 // SPDX-License-Identifier: MPL-2.0
2 // (c) Hare authors <https://harelang.org>
3
4 // TODO: Examine the ABI constraints of [[handle]]. Would it be better to make
5 // stream an integer representing an internal handle into a stream table? This
6 // would reduce performance for streams somewhat via the indirect lookup, but
7 // improve the ABI performance for files.
8
9 // An I/O handle is a resource which I/O operations may be performed on. It is
10 // either a [[stream]], which is a userspace I/O abstraction, or a [[file]],
11 // which is backed by a resource on the host OS, such as a file descriptor.
12 export type handle = (file | *stream);
13
14 // Reads up to len(buf) bytes from a [[handle]] into the given buffer, returning
15 // the number of bytes read.
16 export fn read(h: handle, buf: []u8) (size | EOF | error) = {
17 match (h) {
18 case let fd: file =>
19 return fd_read(fd, buf);
20 case let st: *stream =>
21 return st_read(st, buf);
22 };
23 };
24
25 // Writes up to len(buf) bytes to the [[handle]] from the given buffer,
26 // returning the number of bytes written.
27 export fn write(h: handle, buf: const []u8) (size | error) = {
28 match (h) {
29 case let fd: file =>
30 return fd_write(fd, buf);
31 case let st: *stream =>
32 return st_write(st, buf);
33 case =>
34 abort();
35 };
36 };
37
38 // Closes a [[handle]]. No further operations against this handle are permitted
39 // after calling this function. Closing a file handle can fail only under
40 // certain conditions (for example, closing a file twice, or an interrupted
41 // syscall). However, the user should not attempt to close the file again on
42 // failure - at best the user should print a diagnostic message and move on. See
43 // close(2) for details.
44 export fn close(h: handle) (void | error) = {
45 match (h) {
46 case let fd: file =>
47 fd_close(fd)?;
48 case let st: *stream =>
49 st_close(st)?;
50 };
51 };
52
53 // Sets the offset within a [[handle]], returning the new offset. The new offset
54 // is obtained by adding [[off]] to the position specified by [[whence]].
55 export fn seek(h: handle, off: off, w: whence) (off | error) = {
56 match (h) {
57 case let fd: file =>
58 return fd_seek(fd, off, w);
59 case let st: *stream =>
60 return st_seek(st, off, w);
61 };
62 };
63
64 // Returns the current offset within a [[handle]].
65 export fn tell(h: handle) (off | error) = {
66 return seek(h, 0, whence::CUR);
67 };