autodoc.git/ traditional_manual/ chapter_9.html

Branch: Tag:

2014-09-03

2014-09-03 18:30:32 by Per Hedbor <ph@opera.com>

Added buffered asynchronous I/O mode to Stdio.File

In this mode the input and output is kept in buffers in the file object.
Adding data to the output buffer will write it to the filedescriptor, and
the read callback will receive the input buffer as its argument.

The write callback will have the output buffer as a second argument,
but most of the time this can be ignored since you keep the buffer
object around.

The write callback will only be called if the buffer needs more data,
so if you implement a range_error function in the buffer that refills
the buffer it will only be called once that callback returns 0.

1533:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>set_buffer_mode</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_buffer_mode</span>(</b><code class='object unresolved'>Stdio.IOBuffer</code>|<code class='datatype'>void</code> <code class='argument'>in</code>, <code class='object unresolved'>Stdio.IOBuffer</code>|<code class='datatype'>void</code> <code class='argument'>out</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Toggle the file to IOBuffer mode.</p> + <p> In this mode reading and writing will be done from IOBuffer objects,</p> + <p> It is assumed that the file will be used in non-blocking mode.</p> + <p> If <code>in</code> or <code>out</code> that specific buffer is used for the specified direction.</p> + <p> The default is to create new buffers for both directions when +  this function is called.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Normally you call <code>write</code> to re-trigger the write callback if +  you do not output anything in it (which will stop it from +  re-occuring again).</p> + <p> This will work with buffered mode as well, but simply adding more +  data to the output buffer will work as well.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span>   <span class='homogen--name'><b>set_callbacks</b></span>   </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_callbacks</span>(</b><code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_cb</code><b>)</b></code></p></dd> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_callbacks</span>(</b><code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>|<code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>void</code>|<code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_cb</code><b>)</b></code></p></dd>      <dt class='head--doc'>Description</dt>   <dd class='body--doc'><p>Installs all the specified callbacks at once. Use <code>UNDEFINED</code>
1567:   <span class='homogen--name'><b>set_fs_event_callback</b></span><br>   </dt>   <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_read_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code><b>)</b></code><br> + <code><code class='datatype'>void</code> <b><span class='method'>set_read_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code><b>)</b></code><br>   <code><code class='datatype'>void</code> <b><span class='method'>set_write_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code><b>)</b></code><br> -  + <code><code class='datatype'>void</code> <b><span class='method'>set_write_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code><b>)</b></code><br>   <code><code class='datatype'>void</code> <b><span class='method'>set_read_oob_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_cb</code><b>)</b></code><br>   <code><code class='datatype'>void</code> <b><span class='method'>set_write_oob_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_cb</code><b>)</b></code><br>   <code><code class='datatype'>void</code> <b><span class='method'>set_close_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_cb</code><b>)</b></code><br>
1588:   <ul>   <li><p>When data arrives on the stream, <code>read_cb</code> will be called with    some or all of that data as the second argument.</p> + <p> If the file is in buffer mode, the second argument will be an IOBuffer.</p> + <p> This will always be the same buffer, so data you do not use in +  one read callback can be simply left in the buffer, when new +  data arrives it will be appended</p>   </li><li><p>When the stream has buffer space over for writing, <code>write_cb</code>    will be called so that you can write more data to it.</p>   <p> This callback is also called after the remote end of a socket
1596:    If the remote end has closed both directions simultaneously    (the usual case), Pike will first attempt to call <code>close_cb</code>,    then this callback (unless <code>close_cb</code> has closed the stream).</p> + <p> If the file is in buffer mode, the second argument will be an IOBuffer.</p> + <p> You should add data to write to this buffer.</p>   </li><li><p>When out-of-band data arrives on the stream, <code>read_oob_cb</code>    will be called with some or all of that data as the second    argument.</p>
1772:   <dt class='head--type'><span class='homogen--type'>Method</span>   <span class='homogen--name'><b>set_nonblocking</b></span>   </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_callback</code><b>)</b></code><br> - <code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_callback</code><b>)</b></code><br> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>|<code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>read_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>void</code>|<code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>write_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_callback</code><b>)</b></code><br> + <code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>|<code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>read_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>void</code>|<code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>write_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_callback</code><b>)</b></code><br>   <code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><b>)</b></code></p></dd>      <dt class='head--doc'>Description</dt>
6112:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>__fd_set_output</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>__fd_set_output</span>(</b><code class='datatype'>object</code> <code class='argument'>f</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>This tells the buffer to trigger the write callback for the +  specified filedescriptor when data is added to the buffer.</p> + <p> This is used internally by Stdio.File to handle nonblocking +  buffered mode, and is not really intended to be used directly.</p> + <p> If f is 0 the state is cleared.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span>   <span class='homogen--name'><b>_encode</b></span><br>   <span class='homogen--type'>Method</span>   <span class='homogen--name'><b>_decode</b></span><br>