These Wiki pages will be used to coordinate development of the ChucK I/O API specification. The ChucK I/O API will consist of a main
IO class with methods universal to all types of I/O, and three subclasses:
ChucK I/O Conventions
I/O operations in ChucK are asynchronous by default. Calling an I/O function places the desired I/O operation in a queue, so that I/O does not interfere with real-time audio. This means that after some I/O function has been executed, you cannot be sure at any subsequent line of code that the operation has actually finished unless you do one of the following:
- Call the
finishfunction, which waits for all queued I/O operations to finish without advancing time.
- Advance time until the I/O queue is cleared, by writing something like
myIO => now;.
This class cannot be instantiated. In ChucK code, its main purpose is to enable functions to accept and read from any kind of I/O class without regard to the type of I/O that is taking place. This class deliberately includes no "open" methods to start I/O, since this differs greatly depending on whether you are opening a file, a network socket, or a pipe.
fun void close()
- Closes the I/O stream in the appropriate way (close file, close socket, etc.).
fun void finish()
- Wait for the I/O operation to finish without advancing time.
fun int isIdle()
- Returns true if there are no queued I/O operations, false otherwise.
fun string read(int length)
- Reads up to the specified number of bytes into a string.
fun string readLine()
- Reads everything up to and including the next newline character into a string.
fun int readInt()
- Reads in one integer.
fun int readFloat()
- Reads in one float.
fun int eof()
- Returns true if end of file has been reached (or the network connection has been closed), or false otherwise.
fun void write(string s)
- Writes out the specified string.
fun void writef(string s, ...)
- Writes out the specified string, generated using printf-style conversion specifications.
fun void write(int i)
- Writes out the specified int.
fun void write(float f)
- Writes out the specified float.
Chucking an IO object to now (for example, as in
myIO => now;) causes time to be advanced until all queued I/O operations for that object have completed.
TODO: write example code for this class.