Hi all, I'm in the process of reading through some of the PDDs, and have noticed a couple of points in some of them where it's not clear to me what's going on, or there is a todo item mentioned, or there is a section which says that more discussion needs to occur. Therefore, I thought it'd be a good idea to stimulate some discussion on list, so that something can be distilled from this to help out our architect and those brave enough to implement the design :-) I personally don't have much knowledge about many of the things I'm going to mention in this (and subsequent) emails, so if I say something silly, please don't be too annoyed.
To begin with, I'm going to mention items in pdd22; the design document about Parrot's I/O subsystem. Why start here? Well, it just so happened to be in front of me on my desk :-) =item * In the Composition subsection of the Implementation section there are the sentences: To find an I/O function, the layer stack is searched downwards until a non-NULL function pointer is found for that particular slot. This implementation will be replaced with a composition model. Has the composition model been designed? Or has it been implemented? Are we still left with the stack-based implementation? =item * Later, under the Status Object PMC API there is the comment: Returns an integer status for the status object, 1 for successful completion, -1 for an error, and 0 while still running. [Discuss: This is largely to preserve current expectations of -1 for an error. If we move away from that, is there a better representation?] We should discuss if there is a better representation and make the relevant design decision. =item * Under "Retrieving and setting stream properties" there is a paragraph about the C<poll> opcode which states: Polls a stream or socket object for particular types of events (an integer flag) at a frequency set by seconds and microseconds (the final two integer arguments). [At least, that's what the documentation in src/io/io.c says. In actual fact, the final two arguments seem to be setting the timeout, exactly the same as the corresponding argument to the system version of C<poll>.] What does io.c actually do? What should it do? Are the tests written for the "implemented" behaviour, or for the "documented" behaviour? =item * There are three deprecated opcodes mentioned: C<write>, C<get_fd>, and C<pioctl>. Have we removed these yet? Are they listed as deprecated? Should they be deprecated? =item * Under "Filesystem Opcodes" there is a large comment about possibly moving these opcodes onto methods of the ParrotIO object. We should really discuss this and make a decision/come to a consensus on that point. Within the same subsection there is the text: C<stat> retrieves information about a file on the filesystem. It takes a string filename or an integer argument of a UNIX file descriptor [or an already opened stream object?] Should we be using an already-opened stream object? This point needs discussion. =item * Under "Network I/O Opcodes" there is the comment: 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 object. Keep 'socket' as an opcode, or maybe just make 'socket' an option on creating a new ParrotIO object.] Again, should these opcodes be moved to methods in a role for the ParrotIO object? What are the pros and cons of such a decision? Have we already done this? Again, I just want to get discussion going and a consensus (or executive) decision made. =item * Error Handling Currently some of the networking opcodes (C<connect>, C<recv>, C<send>, C<poll>, C<bind>, and C<listen>) return an integer indicating the status of the call, -1 or a system error code if unsuccessful. Other I/O opcodes (such as C<getfd> and C<accept>) have various different strategies for error notification, and others have no way of marking errors at all. We want to unify all I/O opcodes so they use a consistent strategy for error notification. How should we unify all I/O opcodes? =item * Within the same section is the comment: [Discuss: should synchronous operations take the same error handling strategy as asynchronous ones?] Some form of discussion should take place here to pick apart the issues (if any) and find a design to follow. =cut Ok, I think that's it for this PDD. I'm going to hold off sending more such emails until people think this is a good idea or not. If so, I've edited a few more of the other PDDs and I can summarise what looks to me like should be discussed so that we can firm up the design a bit more. Hopefully this will help us get to 1.0 that bit faster! If you got this far through the email - thanks! Paul
