1 # Copyright (C) 2001-2010, Parrot Foundation.
8 Parrot's I/O subsystem.
16 A "stream" allows input or output operations on a source/destination
17 such as a file, keyboard, or text console. Streams are also called
18 "filehandles", though only some of them have anything to do with files.
24 =item - Parrot I/O objects support both streams and network I/O.
26 =item - Parrot has both synchronous and asynchronous I/O operations.
28 =item - Asynchronous operations must interact safely with Parrot's other
35 =head3 Platform Implementation
37 Parrot uses a series of macros and conditional compilation to generate
38 code to handle IO on various platforms. There is a "portable" version of
39 the IO system that is used for most systems that use a common POSIX API
40 for IO, and there are platform-specific files that can be used for systems
41 that do not subscribe, or don't subscribe faithfully, to POSIX.
43 A series of macros and conditional compilation are used to determine which
44 files get added to the build, and which functions are called to implement
47 =head3 Concurrency Model for Asynchronous I/O
49 Currently, Parrot only implements synchronous I/O operations. Initially,
50 the asynchronous operations will be implemented separately from the
51 synchronous ones. There may be an implementation that uses one variant
52 to implement the other someday, but it's not an immediate priority.
54 Synchronous opcodes are differentiated from asynchronous opcodes by the
55 presence of a callback argument in the asynchronous calls. Asynchronous
56 calls that don't supply callbacks (perhaps if the user wants to manually
57 check later if the operation succeeded) are enough of a fringe case that
58 they don't need opcodes. They can access the functionality via methods
61 Asynchronous operations use a lightweight concurrency model. At the user
62 level, Parrot follows the callback function model of asynchronous I/O.
63 At the interpreter level, each asynchronous operation registers a task
64 with the interpreter's concurrency scheduler. The registered task could
65 represent a simple Parrot asynchronous I/O operation, a platform-native
66 asynchronous I/O call, or even synchronous code in a full Parrot thread
67 (rare but possibly useful for prototyping new features, or for mock
70 Communication between the calling code and the asynchronous operation
71 task is handled by a shared status object. The operation task updates
72 the status object whenever the status changes, and the calling code can
73 check the status object at any time. The status object contains a
74 reference to the returned result of an asynchronous I/O call. In order
75 to allow sharing of the status object, asynchronous ops both pass the
76 status object to the callback PMC, and return it to the calling code.
78 The lightweight tasks typically used by the asynchronous I/O system
79 capture no state other than the arguments passed to the I/O call, and
80 share no variables with the calling code other than the status object.
82 =head3 FileHandle PMC API
92 $P0 = new [ 'FileHandle' ]
96 Creates a new I/O stream object. [Note that this is usually performed
97 via the C<open> opcode.]
104 $P0 = $P1.'open'($S2)
105 $P0 = $P1.'open'($S2, $S3)
109 Opens a stream on an existing I/O stream object, and returns a status
110 object. With no arguments, it can be used to reopen a previously opened
111 I/O stream. $S2 is a file path and $S3 is an optional mode for the
112 stream (read, write, read/write, etc), using the same format as the
113 C<open> opcode: 'r' for read, 'w' for write, 'a' for append, and 'p' for
114 pipe. When the optional mode argument is not passed, the default is read mode.
115 When the mode is set to write or append, a file is created without warning if
116 none exists. When the mode is read (without write), a nonexistent file is an
119 The asynchronous version takes a PMC callback as an additional final
120 argument. When the open operation is complete, it invokes the callback
121 with a single argument: a status object containing the opened stream
129 $P0 = $P1.'close'($P2)
133 Closes an I/O stream, but leaves destruction of the I/O object to the
134 GC. The C<close> method returns a PMC status object.
136 The asynchronous version takes an additional final PMC callback argument
137 $P1. When the close operation is complete, it invokes the callback,
138 passing it a status object. [There's not really much advantage in this
139 over just leaving the object for the GC to clean-up, but it does give
140 you the option of executing an action when the stream has been closed.]
146 $P0 = $P1.'print'($I2)
147 $P0 = $P1.'print'($N2)
148 $P0 = $P1.'print'($S2)
149 $P0 = $P1.'print'($P2)
150 $P0 = $P1.'print'($I2, $P3)
151 $P0 = $P1.'print'($N2, $P3)
152 $P0 = $P1.'print'($S2, $P3)
153 $P0 = $P1.'print'($P2, $P3)
157 Writes an integer, float, string, or PMC value to an I/O stream object.
158 Returns a PMC status object.
160 The asynchronous version takes an additional final PMC callback
161 argument $P2. When the print operation is complete, it invokes the callback,
162 passing it a status object.
168 $S0 = $P1.'read'($I2)
169 $P0 = $P1.'read'($I2, $P3)
173 Retrieves a specified number of bytes ($I2) from a stream $P1 into a
174 string $S0. By default it reads in bytes, but the FileHandle object can
175 be configured to read in code points instead, by setting the character
176 set and encoding on the filehandle object. If there are fewer bytes
177 remaining in the stream than specified in the read request, it returns
178 the remaining bytes (with no error).
180 The asynchronous version takes an additional final PMC callback argument
181 $P3, and only returns a status object $P0. When the read operation is
182 complete, it invokes the callback, passing it a status object. The
183 status object contains the return value: a string that may be in bytes
184 or codepoints depending on the read mode of the I/O object. [The
185 callback doesn't need to know the read mode of the original operation,
186 as the information about the character encoding of the return value is
187 contained in the string.]
193 $S0 = $P1.'readline'()
194 $P0 = $P1.'readline'($P2)
198 Retrieves a single line from a stream $P1 into a string $S1. Calling
199 C<readline> flags the stream as operating in line-buffer mode (see the
200 C<buffer_type> method below). The C<readline> operation respects the
201 read mode of the I/O object the same as C<read> does. Newlines are not
202 removed from the end of the string.
204 The asynchronous version takes an additional final PMC callback argument
205 $P2, and only returns a status object $P0. When the readline operation
206 is complete, it invokes the callback, passing it a status object and a
213 $S0 = $P1.'readall'()
214 $P0 = $P1.'readall'($P2)
216 $S0 = $P1.'readall'($S2)
217 $P0 = $P1.'readall'($S2, $P3)
221 Retrieves the entire contents from a stream $P1 into a string $S0. On a
222 previously opened stream, C<readall> will read the entire contents of
223 the file, and return them as a string. It will respect the read mode of
224 the I/O object the same as C<read> does.
226 On an unopened stream, if a string file path is passed in $S2,
227 C<readall> will open a stream on the file, read the contents and close
230 The asynchronous version takes an additional final PMC callback argument
231 ($P2 or $P3), and only returns a status object $P0. When the readall operation
232 is complete, it invokes the callback, passing it a status object and a
235 =item C<record_separator>
239 $S0 = $P1.'record_separator'()
240 $P0.'record_separator'($S1)
244 Accessor (get and set) for the I/O stream's record separator attribute.
245 The default value is a newline (CR, LF, CRLF, etc. depending on the
252 $S0 = $P1.'buffer_type'()
253 $P0.'buffer_type'($S1)
257 Accessor (get and set) for the I/O stream's buffer type attribute. The
258 attribute is set or returned as a string value of 'unbuffered' (bytes sent as
259 soon as possible), 'line-buffered' (bytes sent when record separator is
260 encountered), or 'full-buffered' (bytes sent when the buffer is full).
266 $I0 = $P1.'buffer_size'()
267 $P0.'buffer_size'($I1)
271 Accessor (get and set) for the I/O stream's buffer size attribute. The
272 size is specified in bytes (positive integer value), though the buffer
273 may hold a varying number of characters when dealing with an encoding of
274 multi-byte codepoints. The code that implements the handling of a
275 particular character set must provide the logic that marks the buffer as
276 "full" when it can't hold the next codepoint even if there are empty
279 Setting the buffer size turns on full buffering mode for the I/O stream.
280 The set buffer size is taken as a minimum, the I/O subsystem may round
281 it up to a standard block size.
283 The buffer is automatically flushed when the buffer size is changed. If
284 the new size was larger than the existing data in the buffer, a size
285 change would be non-disruptive, but if the new size was smaller,
286 resizing it without flushing would truncate the buffer.
296 Accessor (get only) for the I/O stream's read mode. This returns the mode
297 string used to open the I/O stream.
303 $S0 = $P1.'encoding'()
308 Accessor (get and set) for the I/O stream's encoding attribute. Currently,
309 the only valid value to set is 'utf8' which turns on UTF-8 reading/writing
310 mode for the stream. The default behavior is fixed-width 8-bit characters.
320 For stream objects that are simple wrappers around a Unix filehandle,
321 C<get_fd> retrieves the Unix integer file descriptor of the object.
322 This method will simply return -1 on stream objects that aren't Unix
325 No asynchronous version.
329 =head3 Status Object PMC API
333 =item C<get_integer> (vtable)
341 Returns an integer status for the status object, 1 for successful
342 completion, -1 for an error, and 0 while still running. [Discuss: This
343 is largely to preserve current expectations of -1 for an error. If we
344 move away from that, is there a better representation?]
346 =item C<get_bool> (vtable)
356 Returns a boolean status for the status object, C<true> for successful
357 completion or while still running, C<false> for an error.
367 Retrieves the return value of the asynchronous operation from the status
368 object. Returns a NULL PMC while still running, or if the operation had
379 Retrieves the error object from the status object, if the execution of
380 the asynchronous operation terminated with an error. The error object is
381 derived from Exception, and can be thrown from the callback. If there
382 was no error, or the asynchronous operation is still running, returns a
393 Throw an exception from the status object if it contains an error
394 object, otherwise do nothing.
398 =head3 I/O Iterator PMC API
400 [Implementation NOTE: this may either be the default Iterator object
401 applied to a FileHandle or Socket object, a separate Iterator object for
402 I/O objects, or an Iterator role applied to I/O objects.]
410 new $P0, [ 'Iterator' ], $P1
414 Create a new iterator object $P0 from I/O object $P1.
424 Retrieve the next line/block $S0 from the I/O iterator $P1. The amount
425 of data retrieved in each iteration is determined by the I/O object's
426 C<buffer_type> setting: unbuffered, line-buffered, or fully-buffered.
428 =item C<get_bool> (vtable)
432 unless $P0 goto iter_end
436 Returns a boolean value for the iterator, C<true> if there is more data
437 to pull from the I/O object, C<false> if the iterator has reached the
438 end of the data. [NOTE: this means that an iterator always checks for
439 the next line/block of data when it retrieves the current one.]
445 The signatures for the asynchronous operations are nearly identical to
446 the synchronous operations, but the asynchronous operations take an
447 additional argument for a callback, and the only return value from the
448 asynchronous operations is a status object. When the callbacks are invoked,
449 they are passed the status object as their sole argument. Any return
450 values from the operation are stored within the status object.
452 The listing below says little about whether the opcodes return error
453 information. For now assume that they can either return a status object,
454 or return nothing. Error handling is discussed more thoroughly below in
457 =head3 I/O Stream Opcodes
459 =head4 Opening and closing streams
465 =begin PIR_FRAGMENT_INVALID
474 =end PIR_FRAGMENT_INVALID
476 Opens a stream object based on a file path in $S1 and returns it. The
477 stream object defaults to read/write mode. The optional string argument
478 $S2 specifies the mode of the stream (read, write, append, read/write,
479 etc.). Currently the mode of the stream is set with a string argument
480 similar to Perl 5 syntax, but a language-agnostic mode string is
481 preferable, using 'r' for read, 'w' for write, 'a' for append, and 'p'
484 The asynchronous version takes a PMC callback as an additional final
485 argument. When the open operation is complete, it invokes the callback
486 with a single argument: a status object containing the opened stream
491 =begin PIR_FRAGMENT_INVALID
498 =end PIR_FRAGMENT_INVALID
500 Closes a stream object. It takes a single string object argument and
501 returns a status object.
503 The asynchronous version takes an additional final PMC callback
504 argument. When the close operation is complete, it invokes the callback,
505 passing it a status object.
509 =head4 Retrieving existing streams
511 These opcodes do not have asynchronous variants.
517 C<getstdin>, C<getstdout>, and C<getstderr> return a stream object for
518 standard input, standard output, and standard error, respectively.
522 C<fdopen> converts an existing and already open UNIX integer file
523 descriptor into a stream object. It also takes a string argument to
528 =head4 Writing to streams
534 =begin PIR_FRAGMENT_INVALID
549 =end PIR_FRAGMENT_INVALID
551 Writes an integer, float, string, or PMC value to a stream. It
552 writes to standard output by default, but optionally takes a PMC
553 argument to select another stream to write to.
555 The asynchronous version takes an additional final PMC callback
556 argument. When the print operation is complete, it invokes the callback,
557 passing it a status object.
561 =begin PIR_FRAGMENT_INVALID
570 =end PIR_FRAGMENT_INVALID
572 Writes an integer, float, string, or PMC value to standard error.
574 There is no asynchronous variant of C<printerr>. [It's just a shortcut.
575 If they want an asynchronous version, they can use C<print>.]
579 =head4 Reading from streams
585 =begin PIR_FRAGMENT_INVALID
591 $P0 = read $P1, $I2, $P3
593 =end PIR_FRAGMENT_INVALID
595 Retrieves a specified number of bytes, $I2, from a stream, $P2, into a
596 string, $S0. [Note this is bytes, not codepoints.] By default it reads
597 from standard input, but it also takes an alternate stream object source
598 as an optional argument.
600 The asynchronous version takes an additional final PMC callback
601 argument, and only returns a status object. When the read operation is
602 complete, it invokes the callback, passing it a status object and a
607 =begin PIR_FRAGMENT_INVALID
612 $P0 = readline $P1, $P2
614 =end PIR_FRAGMENT_INVALID
616 Retrieves a single line from a stream into a string. Calling
617 C<readline> flags the stream as operating in line-buffer mode.
619 The asynchronous version takes an additional final PMC callback
620 argument, and only returns a status object. When the readline operation
621 is complete, it invokes the callback, passing it a status object and a
626 =begin PIR_FRAGMENT_INVALID
633 =end PIR_FRAGMENT_INVALID
635 [C<peek>, C<seek>, C<tell>, and C<poll> are all candidates for moving from
636 opcodes to FileHandle object methods.]
638 C<peek> retrieves the next byte from a stream into a string, but doesn't
639 remove it from the stream. By default it reads from standard input, but
640 it also takes a stream object argument for an alternate source.
642 There is no asynchronous version of C<peek>. [Does anyone have a line
643 of reasoning why one might be needed? The concept of "next byte" seems
644 to be a synchronous one.]
648 =head4 Retrieving and setting stream properties
654 =begin PIR_FRAGMENT_INVALID
659 seek $P0, $I1, $I2, $I3
660 seek $P0, $I1, $I2, $P3
661 seek $P0, $I1, $I2, $I3, $P4
663 =end PIR_FRAGMENT_INVALID
665 Sets the current file position of a stream object, $P0, to an integer
666 byte offset, $I1, from an integer starting position, $I2, (0 for the
667 start of the file, 1 for the current position, and 2 for the end of the
668 file). It also has a 64-bit variant that sets the byte offset by two
669 integer arguments, $I1 and $I2, (one for the first 32 bits of the 64-bit
670 offset, and one for the second 32 bits). [The two-register emulation for
671 64-bit integers may be deprecated in the future.]
673 The asynchronous version takes an additional final PMC callback
674 argument. When the seek operation is complete, it invokes the callback,
675 passing it a status object and the stream object it was called on.
679 =begin PIR_FRAGMENT_INVALID
684 ($I0, $I1) = tell $P2
686 =end PIR_FRAGMENT_INVALID
688 Retrieves the current file position of a stream object. It also has a
689 64-bit variant that returns the byte offset as two integers (one for the
690 first 32 bits of the 64-bit offset, and one for the second 32 bits).
691 [The two-register emulation for 64-bit integers may be deprecated in the
694 No asynchronous version.
698 =begin PIR_FRAGMENT_INVALID
700 $I0 = poll $P1, $I2, $I3, $I4
702 =end PIR_FRAGMENT_INVALID
704 Polls a stream or socket object for particular types of events (an
705 integer flag) at a frequency set by seconds and microseconds (the final
706 two integer arguments). [At least, that's what the documentation in
707 src/io/io.c says. In actual fact, the final two arguments seem to be
708 setting the timeout, exactly the same as the corresponding argument to
709 the system version of C<poll>.]
711 See the system documentation for C<poll> to see the constants for event
712 types and return status.
714 This opcode is inherently synchronous (poll is "synchronous I/O
715 multiplexing"), but it can retrieve status information from a stream or
716 socket object whether the object is being used synchronously or
721 =head3 Filesystem Opcodes
723 [Okay, I'm seriously considering moving most of these to methods on the
724 ParrotIO object. More than that, moving them into a role that is
725 composed into the ParrotIO object when needed. For the ones that have
726 the form C<opcodename io_object, arguments>, I can't see that it's
727 much less effort than C<io_object.'methodname'(arguments)> for either
728 manually writing PIR or generating PIR. The slowest thing about I/O is
729 I/O, so I can't see that we're getting much speed gain out of making
730 them opcodes. The ones to keep as opcodes are C<unlink>, C<rmdir>, and
737 C<stat> retrieves information about a file on the filesystem. It takes a
738 string filename or an integer argument of a UNIX file descriptor [or an
739 already opened stream object?], and an integer flag for the type of
740 information requested. It returns an integer containing the requested
741 information. The following constants are defined for the type of
742 information requested (see F<runtime/parrot/include/stat.pasm>):
745 Whether the file exists.
747 The size of the file.
749 Whether the file is a directory.
751 Whether the file is a device such as a terminal or a disk.
753 The time the file was created.
754 (Currently just returns -1.)
756 The last time the file was accessed.
758 The last time the file data was changed.
760 The last time the file metadata was changed.
762 The last time the file was backed up.
763 (Currently just returns -1.)
765 The user ID of the file.
767 The group ID of the file.
769 The asynchronous version takes an additional final PMC callback
770 argument, and only returns a status object. When the stat operation is
771 complete, it invokes the callback, passing it a status object and an
772 integer containing the status information.
776 C<unlink> deletes a file from the filesystem. It takes a single string
777 argument of a filename (including the path).
779 The asynchronous version takes an additional final PMC callback
780 argument. When the unlink operation is complete, it invokes the
781 callback, passing it a status object.
785 C<rmdir> deletes a directory from the filesystem if that directory is
786 empty. It takes a single string argument of a directory name (including
789 The asynchronous version takes an additional final PMC callback
790 argument. When the rmdir operation is complete, it invokes the callback,
791 passing it a status object.
795 C<opendir> opens a stream object for a directory. It takes a single
796 string argument of a directory name (including the path) and returns a
799 The asynchronous version takes an additional final PMC callback
800 argument, and only returns a status object. When the opendir operation
801 is complete, it invokes the callback, passing it a status object and a
802 newly created stream object.
806 C<readdir> reads a single item from an open directory stream object. It
807 takes a single stream object argument and returns a string containing
808 the path and filename/directory name of the current item. (i.e. the
809 directory stream object acts as an iterator.)
811 The asynchronous version takes an additional final PMC callback
812 argument, and only returns a status object. When the readdir operation
813 is complete, it invokes the callback, passing it a status object and the
818 C<telldir> returns the current position of C<readdir> operations on a
819 directory stream object.
821 No asynchronous version.
825 C<seekdir> sets the current position of C<readdir> operations on a
826 directory stream object. It takes a stream object argument and an
827 integer for the position. [The system C<seekdir> requires that the
828 position argument be the result of a previous C<telldir> operation.]
830 The asynchronous version takes an additional final PMC callback
831 argument. When the seekdir operation is complete, it invokes the
832 callback, passing it a status object and the directory stream object it
837 C<rewinddir> sets the current position of C<readdir> operations on a
838 directory stream object back to the beginning of the directory. It takes
839 a stream object argument.
841 No asynchronous version.
845 C<closedir> closes a directory stream object. It takes a single stream
848 The asynchronous version takes an additional final PMC callback
849 argument. When the closedir operation is complete, it invokes the
850 callback, passing it a status object.
854 =head3 Network I/O Methods
856 Most of these methods take a default set of arguments the same as the standard
857 UNIX interface. Many also take additional optional arguments. There are no
858 network-specific opcodes.
864 C<socket> returns a new socket object from a given address family,
865 socket type, and protocol number (all integers). The socket object's
866 boolean value can be tested for whether the socket was created.
868 The asynchronous version takes an additional final PMC callback
869 argument, and only returns a status object. When the socket operation is
870 complete, it invokes the callback, passing it a status object and a new
875 C<sockaddr> returns an object representing a socket address, generated
876 from a port number (integer) and an address (string).
878 No asynchronous version.
882 C<connect> connects a socket object to an address.
884 The asynchronous version takes an additional final PMC callback
885 argument, and only returns a status object. When the socket operation is
886 complete, it invokes the callback, passing it a status object and the
887 socket object it was called on. [If you want notification when a connect
888 operation is completed, you probably want to do something with that
889 connected socket object.]
893 C<recv> receives a message from a connected socket object. It returns
894 the message in a string.
896 The asynchronous version takes an additional final PMC callback
897 argument, and only returns a status object. When the recv operation is
898 complete, it invokes the callback, passing it a status object and a
899 string containing the received message.
903 C<send> sends a message string to a connected socket object.
905 The asynchronous version takes an additional final PMC callback
906 argument, and only returns a status object. When the send operation is
907 complete, it invokes the callback, passing it a status object.
911 C<sendto> sends a message string to an address specified in an address
912 object (first connecting to the address).
914 The asynchronous version takes an additional final PMC callback
915 argument, and only returns a status object. When the sendto operation is
916 complete, it invokes the callback, passing it a status object.
921 C<bind> binds a socket object to the port and address specified by an
922 address object (the packed result of C<sockaddr>).
924 The asynchronous version takes an additional final PMC callback
925 argument, and only returns a status object. When the bind operation is
926 complete, it invokes the callback, passing it a status object and the
927 socket object it was called on. [If you want notification when a bind
928 operation is completed, you probably want to do something with that
929 bound socket object.]
933 C<listen> specifies that a socket object is willing to accept incoming
934 connections. The integer argument gives the maximum size of the queue
935 for pending connections.
937 There is no asynchronous version. C<listen> marks a set of attributes on
942 C<accept> accepts a new connection on a given socket object, and returns
943 a newly created socket object for the connection.
945 The asynchronous version takes an additional final PMC callback
946 argument, and only returns a status object. When the accept operation
947 receives a new connection, it invokes the callback, passing it a status
948 object and a newly created socket object for the connection. [While the
949 synchronous C<accept> has to be called repeatedly in a loop (once for
950 each connection received), the asynchronous version is only called once,
951 but continues to send new connection events until the socket is closed.]
955 C<shutdown> closes a socket object for reading, for writing, or for all
956 I/O. It takes a socket object argument and an integer argument for the
960 Close the socket object for reading.
962 Close the socket object for writing.
964 Close the socket object.
968 =head3 Error Handling
970 Currently some of the networking opcodes (C<connect>, C<recv>, C<send>,
971 C<poll>, C<bind>, and C<listen>) return an integer indicating the status
972 of the call, -1 or a system error code if unsuccessful. Other I/O
973 opcodes (such as C<accept>) have various different
974 strategies for error notification, and others have no way of marking
975 errors at all. We want to unify all I/O opcodes so they use a consistent
976 strategy for error notification.
978 =head4 Synchronous operations
980 Synchronous I/O operations return an integer status code indicating
981 success or failure in addition to their ordinary return value(s). This
982 approach has the advantage of being lightweight: returning a single
983 additional integer is cheap.
985 [Discuss: should synchronous operations take the same error handling
986 strategy as asynchronous ones?]
989 =head4 Asynchronous operations
991 Asynchronous I/O operations return a status object. The status object
992 contains an integer status code, string status/error message, and
993 boolean success value.
995 An error callback may be set on a status object, though it isn't
996 required. This callback will be invoked if the asynchronous operation
997 terminates in an error condition. The error callback takes one argument,
998 which is the status object containing all information about the failed
999 call. If no error callback is set, then the standard callback will be
1000 invoked, and the user will need to check for error conditions in the
1001 status object as the first operation of the handler code.
1005 At some point in the future, I/O objects may also provide a way to throw
1006 exceptions on error conditions. This feature will be enabled by calling
1007 a method on the I/O object to set an internal flag. The exception
1008 throwing will be implemented as a method call on the status object.
1010 Note that exception handlers for asynchronous I/O operations will likely
1011 have to be set at a global scope because execution will have left the
1012 dynamic scope of the I/O call by the time the error occurs.
1016 The transition from IPv4 to IPv6 is in progress, though not likely to be
1017 complete anytime soon. Most operating systems today offer at least
1018 dual-stack IPv6 implementations, so they can use either IPv4 or IPv6,
1019 depending on what's available. Parrot also needs to support either
1020 protocol. For the most part, the network I/O opcodes should internally
1021 handle either addressing scheme, without requiring the user to specify
1022 which scheme is being used.
1024 IETF recommends defaulting to IPv6 connections and falling back to IPv4
1025 connections when IPv6 fails. This would give us more solid testing of
1026 Parrot's compatibility IPv6, but may be too slow. Either way, it's a
1027 good idea to make setting the default (or selecting one exclusively) an
1028 option when compiling Parrot.
1030 The most important issues for Parrot to consider with IPv6 are:
1036 Support 128 bit addresses. IPv6 addresses are colon-separated
1037 hexadecimal numbers, such as C<20a:95ff:fef5:7e5e>.
1041 Any address parsing should be able to support the address separated from
1042 a port number or prefix/length by brackets: C<[20a:95ff:fef5:7e5e]:80>
1043 and C<[20a:95ff::]/64>.
1047 Packed addresses, such as the result of the C<sockaddr> opcode, should
1048 be passed around as an object (or at least a structure) rather than as a
1053 See the relevant IETF RFCs: "Application Aspects of IPv6 Transition"
1054 (http://www.ietf.org/rfc/rfc4038.txt) and "Basic Socket Interface
1055 Extensions for IPv6" (http://www.ietf.org/rfc/rfc3493.txt).
1059 L<http://en.wikipedia.org/wiki/Asynchronous_I/O> for a relatively
1060 comprehensive list of asynchronous I/O implementation options.
1064 F<src/io/core.c>, F<src/ops/io.ops>, F<include/parrot/io.h>,
1065 F<runtime/parrot/library/Stream/*>, F<src/io/unix.c>, F<src/io/win32.c>,
1066 Perl 5's IO::AIO, and POE
1074 vim: expandtab shiftwidth=4: