Author: allison
Date: Wed Nov 19 17:50:32 2008
New Revision: 32918
Modified:
trunk/docs/pdds/pdd22_io.pod
Changes in other areas also in this revision:
Added:
trunk/include/parrot/io_portable.h
- copied unchanged from r32916, /branches/pdd22io/include/parrot/io_portable.h
trunk/include/parrot/io_unix.h
- copied unchanged from r32916, /branches/pdd22io/include/parrot/io_unix.h
trunk/include/parrot/io_win32.h
- copied unchanged from r32916, /branches/pdd22io/include/parrot/io_win32.h
trunk/src/io.c
- copied unchanged from r32916, /branches/pdd22io/src/io.c
trunk/src/io/api.c
- copied unchanged from r32916, /branches/pdd22io/src/io/api.c
trunk/src/io/buffer.c
- copied unchanged from r32916, /branches/pdd22io/src/io/buffer.c
trunk/src/io/portable.c
- copied unchanged from r32916, /branches/pdd22io/src/io/portable.c
trunk/src/io/unix.c
- copied unchanged from r32916, /branches/pdd22io/src/io/unix.c
trunk/src/io/unix_socket.c
- copied unchanged from r32916, /branches/pdd22io/src/io/unix_socket.c
trunk/src/io/win32.c
- copied unchanged from r32916, /branches/pdd22io/src/io/win32.c
trunk/src/io/win32_socket.c
- copied unchanged from r32916, /branches/pdd22io/src/io/win32_socket.c
trunk/src/pmc/filehandle.pmc
- copied unchanged from r32916, /branches/pdd22io/src/pmc/filehandle.pmc
trunk/t/pmc/filehandle.t
- copied unchanged from r32916, /branches/pdd22io/t/pmc/filehandle.t
Modified:
trunk/MANIFEST
trunk/config/gen/makefiles/root.in
trunk/include/parrot/io.h
trunk/lib/Parrot/Pmc2c/Parser.pm
Log:
[pdd22io] Merging the pdd22io branch into trunk for r32120 to r32916.
Modified: trunk/docs/pdds/pdd22_io.pod
==============================================================================
--- trunk/docs/pdds/pdd22_io.pod (original)
+++ trunk/docs/pdds/pdd22_io.pod Wed Nov 19 17:50:32 2008
@@ -49,11 +49,10 @@
=head2 Concurrency Model for Asynchronous I/O
-Currently, Parrot only implements synchronous I/O operations. For the
-1.0 release the asynchronous operations will be implemented separately
-from the synchronous ones. There may be an implementation that uses one
-variant to implement the other someday, but it's not an immediate
-priority.
+Currently, Parrot only implements synchronous I/O operations. Initially,
+the asynchronous operations will be implemented separately from the
+synchronous ones. There may be an implementation that uses one variant
+to implement the other someday, but it's not an immediate priority.
Synchronous opcodes are differentiated from asynchronous opcodes by the
presence of a callback argument in the asynchronous calls. Asynchronous
@@ -90,7 +89,7 @@
[See L<http://en.wikipedia.org/wiki/Asynchronous_I/O>, for a relatively
comprehensive list of asynchronous I/O implementation options.]
-=head2 I/O PMC API
+=head2 FileHandle PMC API
Methods
@@ -108,7 +107,7 @@
=item C<new>
- $P0 = new ParrotIO
+ $P0 = new 'FileHandle'
Creates a new I/O stream object. [Note that this is usually performed
via the C<open> opcode.]
@@ -124,9 +123,10 @@
I/O stream. $S2 is a file path and $S3 is an optional mode for the
stream (read, write, read/write, etc), using the same format as the
C<open> opcode: 'r' for read, 'w' for write, 'a' for append, and 'p' for
-pipe. When the mode is set to write or append, a file is created without
-warning if none exists. When the mode is read (without write), a
-nonexistent file is an error.
+pipe. When the optional mode argument is not passed, the default is read mode.
+When the mode is set to write or append, a file is created without warning if
+none exists. When the mode is read (without write), a nonexistent file is an
+error.
The asynchronous version takes a PMC callback as an additional final
argument. When the open operation is complete, it invokes the callback
@@ -171,12 +171,11 @@
$P0 = $P1.read($I2, $P3)
Retrieves a specified number of bytes $I2, from a stream $P1 into a
-string $S0. By default it reads in bytes, but the ParrotIO object can be
-configured to read in code points instead, by applying a C<utf8> or
-similar role to the object [the syntax for applying a role to an object
-has yet to be defined in PDD 15]. If there are fewer bytes remaining in
-the stream than specified in the read request, it returns the remaining
-bytes (with no error).
+string $S0. By default it reads in bytes, but the FileHandle object can
+be configured to read in code points instead, by setting the character
+set and encoding on the filehandle object. If there are fewer bytes
+remaining in the stream than specified in the read request, it returns
+the remaining bytes (with no error).
The asynchronous version takes an additional final PMC callback argument
$P3, and only returns a status object $P0. When the read operation is
@@ -214,26 +213,13 @@
=item C<buffer_type>
- $I0 = $P1.buffer_type()
$S0 = $P1.buffer_type()
- $P0.buffer_type($I1)
$P0.buffer_type($S1)
Accessor (get and set) for the I/O stream's buffer type attribute. The
-attribute is returned as an integer value of one of the following
-constants, or a string value of 'unbuffered', 'line-buffered', or
-'full-buffered'.
-
- 0 PIO_NONBUF
- Unbuffered I/O. Bytes are sent as soon as possible.
- 1 PIO_LINEBUF
- Line buffered I/O. Bytes are sent when a record separator is
- encountered.
- 2 PIO_FULLBUF
- Fully buffered I/O. Bytes are sent when the buffer is full.
- [Note, the constant was called "BLKBUF" because bytes are
- sent as a block, but line buffering also sends them as a
- block, so changed to "FULLBUF".]
+attribute is set or returned as a string value of 'unbuffered' (bytes sent as
+soon as possible), 'line-buffered' (bytes sent when record separator is
+encountered), or 'full-buffered' (bytes sent when the buffer is full).
=item C<buffer_size>
@@ -243,19 +229,26 @@
Accessor (get and set) for the I/O stream's buffer size attribute. The
size is specified in bytes (positive integer value), though the buffer
may hold a varying number of characters when dealing with an encoding of
-multi-byte codepoints. The role that implements the handling of a
+multi-byte codepoints. The code that implements the handling of a
particular character set must provide the logic that marks the buffer as
"full" when it can't hold the next codepoint even if there are empty
bytes in the buffer.
-The buffer size can be set no matter what buffering mode is in use, but
-it's only relevant when in line buffering or full buffering mode (and
-line buffering mode will rarely reach the maximum buffer size).
-
-It is recommended to only change the buffer size before starting IO
-operations, or after flushing the buffer. If the new size is larger than
-the existing data in the buffer, a size change is non-disruptive, but if
-the new size is smaller, it will truncate the buffer with a warning.
+Setting the buffer size turns on full buffering mode for the I/O stream.
+The set buffer size is taken as a minimum, the I/O subsystem may round
+it up to a standard block size.
+
+The buffer is automatically flushed when the buffer size is changed. If
+the new size was larger than the existing data in the buffer, a size
+change would be non-disruptive, but if the new size was smaller,
+resizing it without flushing would truncate the buffer.
+
+=item C<mode>
+
+ $S0 = $P1.mode()
+
+Accessor (get only) for the I/O stream's read mode. This returns the mode
+string used to open the I/O stream.
=item C<get_fd> [RT #48312]
@@ -263,15 +256,11 @@
For stream objects that are simple wrappers around a Unix filehandle,
C<get_fd> retrieves the Unix integer file descriptor of the object.
-This method doesn't exist on stream objects that aren't Unix
-filehandles, so check C<does> for the appropriate role, or C<can> for
-the method before calling it.
+This method will simply return -1 on stream objects that aren't Unix
+filehandles.
No asynchronous version.
-{{ NOTE: use a config probe (behind C<does> or C<can>) to determine support }}
-
-
=back
=head2 Status Object PMC API
@@ -324,8 +313,8 @@
=head2 I/O Iterator PMC API
[Implementation NOTE: this may either be the default Iterator object
-applied to a ParrotIO object, a separate Iterator object for I/O
-objects, or an Iterator role applied to I/O objects.]
+applied to a FileHandle or Socket object, a separate Iterator object for
+I/O objects, or an Iterator role applied to I/O objects.]
=over 4
@@ -508,7 +497,7 @@
$S0 = peek $P1
['peek', 'seek', 'tell', and 'poll' are all candidates for moving from
-opcodes to ParrotIO object methods.]
+opcodes to FileHandle object methods.]
C<peek> retrieves the next byte from a stream into a string, but doesn't
remove it from the stream. By default it reads from standard input, but
@@ -588,7 +577,7 @@
and a single integer argument for the command. It returns an integer
indicating the success or failure of the command.
-This opcode has been replaced with methods on the ParrotIO object, but
+This opcode has been replaced with methods on the FileHandle object, but
is kept here for reference. See RT #48589
The following constants are defined for the commands that C<pioctl> can
@@ -628,8 +617,8 @@
[Okay, I'm seriously considering moving most of these to methods on the
ParrotIO object. More than that, moving them into a role that is
composed into the ParrotIO object when needed. For the ones that have
-the form 'C<opcodename parrotIOobject, arguments>', I can't see that it's
-much less effort than 'C<parrotIOobject.methodname(arguments)>' for either
+the form 'C<opcodename io_object, arguments>', I can't see that it's
+much less effort than 'C<io_object.methodname(arguments)>' for either
manually writing PIR or generating PIR. The slowest thing about I/O is
I/O, so I can't see that we're getting much speed gain out of making
them opcodes. The ones to keep as opcodes are 'C<unlink>', 'C<rmdir>', and
@@ -761,9 +750,9 @@
Most of these opcodes conform to the standard UNIX interface, but the
layer API allows alternate implementations for each.
-[These I'm also considering moving to methods in a role for the ParrotIO
+[These I'm also considering moving to methods in a role for the Socket
object. Keep 'socket' as an opcode, or maybe just make 'socket' an
-option on creating a new ParrotIO object.]
+option on creating a new Socket object.]
=over 4
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.