From CSWiki
Revision as of 00:02, 6 March 2008 by Aschran (talk | contribs) (fixed tenses so this can stand as API documentation once finished)

Jump to: navigation, search

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 main subclasses: FileIO, NetIO, and PipeIO.

The following is subject to change.

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 the next line of code that the operation has actually finished unless you do one of the following:

  1. Call the finish function, which waits for all queued I/O operations to finish without advancing time.
  2. Advance time until the I/O queue is cleared, by writing something like myIO => now;.

IO Class

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 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 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.