Log of autodoc.git/traditional_manual/chapter

2014-09-02

2014-09-02 13:05:49 by Per Hedbor <ph@opera.com>

b24a44e332583999ceefb2a2c51e94d67ba9d477 (505 lines) (+3/-502) ^{[

Show
| Annotate

]}
Branch: 8.0

Added support for SO_REUSEPORT when available

2465: <dt class='head--type'>Method bind </dt> - <dd><code><code class='datatype'>int</code> bind(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>ip</code>)</code></dd> + <dd><code><code class='datatype'>int</code> bind(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>ip</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>reuse_port</code>)</code></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'>Opens a socket and binds it to port number on the local machine.
2479: will bind to all available IPv4 addresses; specifying "::" will bind to all IPv4 and IPv6 addresses. If the OS supports TCP_FASTOPEN it is enabled automatically. + If the OS supports SO_REUSEPORT it is enabled if the fourth argument is true. </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'>1 is returned on success, zero on failure. <code>errno</code> provides
6087: <dd class='body--doc'>Fake inherit to propagate the documentation from <code>_Stdio.Fd</code>. </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.IOBuffer</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>A buffer to use as input or buffering when doing I/O. It is - similar to <code>String.Buffer</code>, but can only contain 8bit data and is - designed for protocol parsing. It is optimized for reading from - the beginning and adding to the end, and will try to minimize the - amount of data copying that is done. - It can also directly read from and write to filedescriptors if so - desired. This eliminates at least one memory copy. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _sizeof - </dt> - <dd><code><code class='datatype'>int</code> sizeof( Stdio.IOBuffer arg )</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the buffer size, in bytes. - This is how much you can read from the buffer until it runs out of data. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - `[] - </dt> - <dd><code><code class='datatype'>int</code> res = <code class='class'>Stdio.IOBuffer()</code>[ <code class='class'>off</code> ]</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the character at the specified offset. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - `[]= - </dt> - <dd><code><code class='class'>Stdio.IOBuffer()</code>[ <code class='class'>off</code> ] = <code class='class'>char</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the character at the specified offset to <code>char</code>. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add - </dt> - <dd><code><code class='datatype'>void</code> add(<code class='datatype'>string(8bit)</code>|<code class='datatype'>int(8bit)</code> ... <code class='argument'>data</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add the items in data one at a time. - Integers are assumed to be 8bit numbers (characters) - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_byte - Method - add_int8 - </dt> - <dd><code><code class='datatype'>int</code> add_byte(<code class='datatype'>int(8bit)</code>)</code> - <code><code class='datatype'>int</code> add_int8(<code class='datatype'>int(8bit)</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a single byte to the buffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_hstring - </dt> - <dd><code><code class='datatype'>void</code> add_hstring(<code class='datatype'>string(8bit)</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds length/data for <code>data</code> to the buffer. - This is identical to <code>sprintf("%"+size_size+"H",data)</code> but - significantly faster. - <code>size_size</code> must be less than Int.NATIVE_MAX. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int - </dt> - <dd><code><code class='datatype'>int</code> add_int(<code class='datatype'>int</code> <code class='argument'>i</code>, <code class='datatype'>int(0..)</code> <code class='argument'>width</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a generic integer to the buffer as an (width*8)bit - network byteorder number. - <code>width</code> must be less than Int.NATIVE_MAX. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int16 - Method - add_short - </dt> - <dd><code><code class='datatype'>int</code> add_int16(<code class='datatype'>int(16bit)</code>)</code> - <code><code class='datatype'>int</code> add_short(<code class='datatype'>int(16bit)</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add a 16-bit network byte order value to the buffer - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int32 - </dt> - <dd><code><code class='datatype'>int</code> add_int32(<code class='datatype'>int</code> <code class='argument'>i</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a 32 bit network byte order value to the buffer - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - cast - </dt> - <dd><code>(<code class='datatype'>string</code>)Stdio.IOBuffer()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Convert the buffer to a string. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This only works for buffers whose length is less than 0x7fffffff. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - clear - </dt> - <dd><code><code class='datatype'>void</code> clear()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Clear the buffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - consume - </dt> - <dd><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> consume(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Discard the first <code>n</code> bytes from the buffer - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>Stdio.IOBuffer Stdio.IOBuffer(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>len</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Create a new buffer of the given size. - The buffer will grow if needed, so the length is only the - initial size. - The default initial size is 4K - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>Stdio.IOBuffer Stdio.IOBuffer(<code class='datatype'>string(8bit)</code> <code class='argument'>x</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Create a new buffer with the contents of the given - string. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This will not copy the string data, instead data will - be read from the string until it needs to be modified, so the - buffer creation is fast regardless of the length of the - string. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - lock - </dt> - <dd><code><code class='datatype'>object</code> lock()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Makes this buffer read only until the returned object is released. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This currently simply returns a 0-length subbuffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - match - </dt> - <dd><code><code class='datatype'>mixed</code> match(<code class='datatype'>string(8bit)</code> <code class='argument'>format</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads data from the beginning of the buffer to match the - specifed format, then return the match. - The non-matching data will be left in the buffer. - This function is very similar to <code>sscanf</code>, but the - result is the sum of the matches. Most useful to match - a single value. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>// get the next whitespace separated word from the buffer. - buffer->match("%*[ \t\r\n]%*[^ \t\r\n]"); - </code></pre></pre></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read all data from the buffer. - If there is not enough data available this returns 0. - This is basically equivalent to (string)buffer, but it also - removes the data from the buffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read <code>bytes</code> bytes of data from the buffer. - If there is not enough data available this returns 0. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_buffer - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> read_buffer(<code class='datatype'>int</code> <code class='argument'>n</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> read_buffer(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='object unresolved'>bool</code> <code class='argument'>copy</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Same as <code>read</code>, but returns the result as an IOBuffer. - No data is copied unless <code>copy</code> is specified and true, the new buffer - points into the old one. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>As long as the subbuffer exists no data can be added to the main buffer. - Usually this is OK, since it often represents something that - should be parsed before the next whatever is extracted from - the buffer, but do take care. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_hbuffer - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> read_hbuffer(<code class='datatype'>int</code> <code class='argument'>n</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> read_hbuffer(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='object unresolved'>bool</code> <code class='argument'>copy</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Same as <code>read_hstring</code>, but returns the result as an IOBuffer. - No data is copied unless <code>copy</code> is specified and true, the new - buffer points into the old one. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>As long as the subbuffer exists no data can be added to the - main buffer. - Usually this is OK, since it often represents something that - should be parsed before the next whatever is extracted from - the buffer, but do take care. - If you need to unlink the new buffer after it has been - created, call <code>trim</code> in it. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_hstring - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read_hstring(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Identical in functionality to <code>read</code>(<code>read_number</code>(<code>n</code>)) but - faster. - Read a network byte order number of size n*8 bits, then return the - indicated number of bytes as a string. - If there is not enough data available return 0. - Note that pike string can not be longer than 0x7fffffff bytes (~2Gb). - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int - </dt> - <dd><code><code class='datatype'>int</code> read_int(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a network (if n is positive) or little endian (if n is - negative) byte order unsigned number of size n*8 bits, then - return it. - Will return -1 if there is not enough buffer space available - unless error mode is set to throw errors. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_json - </dt> - <dd><code><code class='datatype'>mixed</code> read_json(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>require_whitespace_separator</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a single JSON expression from the buffer and return it. - If <code>require_whitespace_separator</code> is true there must be a whitespace - after each json value (as an example, newline or space). - The JSON is assumed to be utf-8 encoded. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>UNDEFINED if no data is available to read. - The read value otherwise. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Unless whitespaces are required this function only really work correctly - with objects, arrays and strings. - There is really no way to see where one value starts and the other ends - for most other cases - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_error_mode - </dt> - <dd><code><code class='datatype'>void</code> set_error_mode(<code class='datatype'>int</code> <code class='argument'>m</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the error mode of this buffer to <code>m</code>. - If true operations that would normally return 0 (like trying to read too much) - will instead thrown an error. - This is useful when parsing received data, you do not have to - verify that each and every read operation suceeds. - However, the non-error mode is more useful when checking to see - if a packet/segment/whatever has arrived. - The thrown error object will have the constant buffer_error set - to a non-false value. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>void read_callback(int i, string new_data) - { - inbuffer->add( new_data ); - - while( IOBuffer packet = inbuffer->read_hbuffer(2) ) - { - packet->set_error_mode(Buffer.THROW_ERROR); - if( mixed e = catch( handle_packet( packet ) ) ) - if( e->buffer_error ) - protocol_error(); // illegal data in packet - else - throw(e); // the other code did something bad - } - } - - void handle_packet( IOBuffer pack ) - { - switch( pack->read_int8() ) - { - ... - case HEADER_FRAME: - int num_headers = pack->read_int32(); - for( int i = 0; i<num_headers; i++ ) - headers[pack->read_hstring(2)] = pack->read_hstring(2); - ... - } - } - </code></pre></pre></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - sprintf - </dt> - <dd><code><code class='datatype'>int</code> sprintf(<code class='object unresolved'>strict_sprintf_format</code> <code class='argument'>format</code>, <code class='object unresolved'>sprintf_args</code> ... <code class='argument'>args</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Appends the output from <code>sprintf</code> at the end of the buffer. - This is somewhat faster than add(sprintf(...)) since no - intermediate string is created. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - sscanf - </dt> - <dd><code><code class='datatype'>array</code> sscanf(<code class='datatype'>string(8bit)</code> <code class='argument'>format</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads data from the beginning of the buffer to match the - specifed format, then return an array with the matches. - The non-matching data will be left in the buffer. - See <code>array_sscanf</code> for more information. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - trim - </dt> - <dd><code><code class='datatype'>void</code> trim()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Frees unused memory. - Note that calling this function excessively will slow things - down, since the data often has to be copied. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function could possibly throw an out-of-memory error - if the realloc fails to find a new (smaller) memory area. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - unread - </dt> - <dd><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> unread(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Rewind the buffer <code>n</code> bytes. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns how many more bytes of buffer is - available to rewind, or -1 on error. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Unless you add new data to the buffer using any of the add - functions you can always rewind. - You can call <code>undread(0)</code> to see how much. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - write_to - </dt> - <dd><code><code class='datatype'>void</code> write_to(<code class='object unresolved'>Stdio.Strem</code> <code class='argument'>f</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Write data from the buffer to the indicated file. - Will return the number of bytes that were successfully written. - </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.NonblockingStream</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt>

autodoc.git/ traditional_manual/ chapter_9.html

2014-09-02

2014-09-02 13:05:49 by Per Hedbor <ph@opera.com>