Fri, 16 Nov 2007 11:26:01 -0500
docs: Refactored 'file descriptor' reference
43
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
1 | ---- |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
2 | Functions: |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
3 | |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
4 | [[toc levels=1]] |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
5 | |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
6 | ## buffer.new |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
7 | * Instantiates a new buffer object |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
8 | |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
9 | ## buffer:add |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
10 | * Successively concatenates each of the arguments onto the buffer |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
11 | * Input: `(...)` |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
12 | * Sequence of strings or buffer instances |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
13 | * Side Effects: Buffers 'add'ed are emptied of their contents (per libevent semantics) |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
14 | * Output: Amount of data added |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
15 | (QUESTION: Should add return the buffer itself so that chaining can be easy) |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
16 | |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
17 | ## buffer:length (`__len`) |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
18 | * Output: Length of the remaining buffer contents |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
19 | |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
20 | ## buffer:get\_data (`__tostring`) |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
21 | * Input: |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
22 | * `()` and `__tostring` - Returns all data in the buffer |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
23 | * `(len)` - Returns data up to `len` bytes long |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
24 | * `(begin, len)` - Returns data beginning at `begin` up to `len` bytes long |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
25 | * If `begin < 0`, wraps at data length. Ex: (-1, 1) returns last byte, (-2, 2) returns last 2 bytes |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
26 | * Output: A copy of contents from the buffer |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
27 | |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
28 | ## buffer:read |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
29 | * Reads data from a file-descriptor/socket into the buffer directly |
44
e8e83eac4d9a
docs: Refactored 'file descriptor' reference
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
30 | * Input: `(fd, length)` |
e8e83eac4d9a
docs: Refactored 'file descriptor' reference
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
31 | * `fd` - File descriptor to read from |
43
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
32 | * `length` - Amount of data to attempt to read into the buffer |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
33 | * Output: Length of data actually read into the buffer |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
34 | * Side Effects: fd/socket 'drain'ed of data |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
35 | |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
36 | ## buffer:write |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
37 | * Attempts to write out all buffer's data to a file-descriptor/socket |
44
e8e83eac4d9a
docs: Refactored 'file descriptor' reference
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
38 | * Input: `(fd, length)` |
e8e83eac4d9a
docs: Refactored 'file descriptor' reference
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
39 | * `fd` - File descriptor to write to |
43
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
40 | * `socket` - [LuaSocket](http://www.luaforge.net/projects/luasocket)-based socket handle |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
41 | * Output: Amount of data written |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
42 | * Side Effects: buffer 'drain'ed of written data |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
43 | |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
44 | ## buffer:readline |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
45 | * Reads a line terminated by either '\r\n', '\n\r', '\r', or, '\n' |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
46 | * Output: |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
47 | * If no terminator found: nil |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
48 | * If terminator found: Line returned without terminators |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
49 | * NOTE: If a '\r' or '\n' are the last characters in the buffer, then the data is returned even if the |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
50 | potential later data would contain the paired '\n' or '\r'. (TODO: Ask libevent list on how this is handled...) |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
51 | |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
52 | ## buffer:drain |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
53 | * Removes data from the buffer |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
54 | * Input: `(amt)` |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
55 | * If `amt < 0` drains all data due to auto-casting to unsigned int and capping... |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
56 | TODO: Add code to check this condition explicitly for safety |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
57 | * If `amt >= 0`, drain up to amt from the buffer (no problem w/ too-large values) |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
58 | |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
59 | ## buffer:close (`__gc`) |
f58b30ad545e
Added initial shot at documentation using Ikiwiki (only luaevent.core.buffer is really doc'ed yet)
Thomas Harning Jr <harningt@gmail.com>
parents:
diff
changeset
|
60 | * Immediately frees/closes a buffer. Note that |