Re: PDD for code comments ????
Regarding comments in code: Chopping and misquoting wildly Jarkko Hietaniemi said: * I would define a relatively strict and standard way to do this so that the documentation can be extracted out. * lets avoid a markup-up flamewar Simon Cozens said: * I'd like to see Perl 6 written as a literate program * the apidoc is a really good thing, but it needs to be made more extensible * RFC281 was an initial set of thoughts on this idea. David L. Nicol said: /* =pod =cut */ Whereas I'm about to say Questions: 1. Does anyone *disagree* that we need "a relatively strict and standard way" to document code? 2. Is this the time and place to discuss it? 3. Should the result of the discusssion be a PDD? 4. Are we all agreed that in addition to anything else (eg rfc281), at least some of the standard commentary should appear actually within the src file itself? 5. Does anyone agree or disagree with my proposal for mandatory per file, per section, and per func/struct comments? 5. Do *all* these comments need to be extractable, or only ones related to published APIs etc? 6. Can we leave the details of pod/apidoc/rfc281 until 1..5 have been agreed? 7. What is the average air speed velocity of a swallow, etc etc... Dave M. PS. I decree that this email solves Warnock's Dilemma [*] by assuming that silence implies absolute assent to everything I have ever said or will ever say. ;-) [*] Or should that be quintlemma, or pentlemma, or ? Any Classics scholars out there?
Re: PDD for code comments ????
On Tue, Feb 20, 2001 at 03:49:44PM +, David Mitchell wrote: 4. Are we all agreed that in addition to anything else (eg rfc281), at least some of the standard commentary should appear actually within the src file itself? quote from someone recently "separate documentation is no documentation" (sorry, forget who) which seemed a nice way of describing it. I think it would be good to make it so easy to documented code as you write it that there really would be no excuse not to do it 5. Does anyone agree or disagree with my proposal for mandatory per file, per section, and per func/struct comments? Tolkien quotes are mandatory? perl5's globals.c malloc.c perlio.c perly.c universal.c xsutils.c definitely fail then. [globals.c malloc.c miniperlmain.c perly.c regcomp.c regexp.c taint.c universal.c xsutils.c have no copyright statement.] embed.pl doesn't add a Tolkien quote or a copyright statement to perl API.c 5. Do *all* these comments need to be extractable, or only ones related to published APIs etc? You have 2 point 5s. [I feel there must be a Monty Python quote related to this, but apart from "Rule 6 - there is /no/ rule six" from the Bruces sketch, I'm lost] It would be good to be able to extract documentation relating to the implementation behind the APIs, for guts hackers. PS. I decree that this email solves Warnock's Dilemma [*] by assuming that silence implies absolute assent to everything I have ever said or will ever say. ;-) I don't think "will ever say" holds. And I think I'd phrase it as "ongoing silence". But apart from that, it seems to be a working assumption for design proposals. Nicholas Clark
Tolkein (was Re: PDD for code comments ????)
Tolkien quotes are mandatory? perl5's globals.c malloc.c perlio.c perly.c universal.c xsutils.c definitely fail then. Sounds like some urgent patches need submitting to p5p ;-)
Re: Tolkein (was Re: PDD for code comments ????)
On Tue, Feb 20, 2001 at 05:57:10PM +, David Mitchell wrote: Do we want to go with Tolkein quotes for perl 6 and, if so, who wants to put together a list of good ones? It's been ages since I've read the books, and I'm likely to pull quotes from other places anyway. (Usagi Yojimbo strikes me as a good place to yank from, as does Zot!, but Pratchett will do too...) Err, would that be Larry's prerogative ??? And what about us poor semi-literates who've never heard of Yojimbo ??? If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s read him :-) Adams rather than Pratchett, I'd think. :) -- Roman M. Parparov - NASA EOSDIS project node at TAU technical manager. Email: [EMAIL PROTECTED] http://www.komkon.org/~romm Phone/Fax: +972-(0)3-6405205 (work), +972-(0)54-629-884 (home) -- The economy depends about as much on economists as the weather does on weather forecasters. -- Jean-Paul Kauffmann
Re: Tolkein (was Re: PDD for code comments ????)
Do we want to go with Tolkein quotes for perl 6 and, if so, who wants to put together a list of good ones? It's been ages since I've read the books, and I'm likely to pull quotes from other places anyway. (Usagi Yojimbo strikes me as a good place to yank from, as does Zot!, but Pratchett will do too...) Err, would that be Larry's prerogative ??? And what about us poor semi-literates who've never heard of Yojimbo ??? If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s read him :-)
Re: Tolkein (was Re: PDD for code comments ????)
And what about us poor semi-literates who've never heard of Yojimbo ??? If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s read him :-) Adams rather than Pratchett, I'd think. :) But Pratchet has 20+ books to his credit, so we need never run out of quotes :-)
Re: Tolkein (was Re: PDD for code comments ????)
On Tue, Feb 20, 2001 at 06:06:49PM +, David Mitchell wrote: And what about us poor semi-literates who've never heard of Yojimbo ??? If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s read him :-) Adams rather than Pratchett, I'd think. :) But Pratchet has 20+ books to his credit, so we need never run out of quotes :-) As long as Terry Pratchett writes books faster than perl consumes quotes. Based on the fact that he's still very alive, we aren't in danger yet. However, Larry has already commented on the danger of running out of LOTR quotes: http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-02/msg00369.html Nicholas Clark
Re: Tolkein (was Re: PDD for code comments ????)
At 05:57 PM 2/20/2001 +, David Mitchell wrote: Do we want to go with Tolkein quotes for perl 6 and, if so, who wants to put together a list of good ones? It's been ages since I've read the books, and I'm likely to pull quotes from other places anyway. (Usagi Yojimbo strikes me as a good place to yank from, as does Zot!, but Pratchett will do too...) Err, would that be Larry's prerogative ??? Yep, it would. Hence the call for a list of quotes from LOTR. :) And what about us poor semi-literates who've never heard of Yojimbo ??? If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s read him :-) Sheesh, kids today. You can't even count on anyone having a misspent youth anymore... Dan --"it's like this"--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: Tolkein (was Re: PDD for code comments ????)
On Tue, Feb 20, 2001 at 07:43:11PM +0100, H.Merijn Brand wrote: My name (Merijn) is *from* Tolkien's dutch translation, so I'm a little biases if I state: "Stick with Tolkien". Well, I'm of to Mordor now ... http://www.prembone.com/mythtakes/shiresong.html -- "It's God. No, not Richard Stallman, or Linus Torvalds, but God." (By Matt Welsh)
Re: PDD for code comments ????
David Mitchell wrote: 4. Are we all agreed that in addition to anything else (eg rfc281), at least some of the standard commentary should appear actually within the src file itself? s/at least some/most, if not all/ 5. Do *all* these comments need to be extractable, or only ones related to published APIs etc? Initially the automaton creates them all extractable, and the coder can depod the ones that are implementation details and should not be published, as a measure more extreme than noting "This function is an implementaion detail" in the mandatory comment for the function. Which implies an at least implicit standard lexicon of flexibility to use in these comments, ranging from "implements ISO standard interface" down to "experimental - failed, remove during clean-up phase" 6. Can we leave the details of pod/apidoc/rfc281 until 1..5 have been agreed? I can't. Can you? Altering a C prettyprinter to insert an extensible standard comment template before each function definition would be even easier than writing one from scratch. But what goes in that block of text, beyond /* =pod =head1 function $FunctionName returning $ReturnType =head1 Named arguments: @ArgNameList =cut */
Re: Tolkein (was Re: PDD for code comments ????)
Douglas Adams does seem rather more appropriate a source of quotes for software (anyone's, alas) than Pratchett. But Adams already has a software company. -Hao
Re: Tolkein (was Re: PDD for code comments ????)
Simply Hao wrote: Douglas Adams does seem rather more appropriate a source of quotes for software (anyone's, alas) than Pratchett. But Adams already has a software company. And Sirius pioneered the GPP in Perl 6.
Re: C Garbage collector
Alan Burlison wrote: I've attached the HTML Well it was there when I sent it... does this list strip attachments or something? Here is is as badly-formatted text - sorry! Alan Burlison Appendix A: How Sun WorkShop Memory Monitor Works Memory management in C/C++ is both time consuming and error prone. Typically, about one-third of development time is spent on memory management, and most commercially available programs ship with memory leaks or premature frees. Even worse, no matter how well written your own code is, third-party libraries and DLLs used by your program may leak, leaving you with no way to deliver leak-free applications. Imagine what would happen if memory just freed itself when it was no longer in use. Programs that freed memory in the wrong place would automatically be fixed, and new code wouldn't need to free memory at all. Such automatic garbage collection is the standard in Java and Smalltalk. I'll lift the hood on the Sun WorkShop Memory Monitor garbage collector, focusing on the details that make it practical, transparent, and scalable. Why Garbage Collection? The basic idea behind garbage collection is refreshingly logical. As a program runs, the garbage collector periodically scans the program's data marking everything that is in use. It begins by scanning the program's stack, registers, and the static segment. Every time it encounters a pointer, it marks the object that it points to. Then it scans the object for pointers to other heap objects. Once it has marked all reachable heap objects, it frees all the objects that haven't been marked (see Figure 1). The hard part of adapting garbage collection to C/C++ is identifying pointers. Since object libraries and DLLs often lack source, you can't examine the source for type information, and you can't recompile. Typically, you don't even have debugging information. The only remaining option is to relink. This isn't as bad as it sounds, since relinking lets you redefine whatever functions you like. What functions should you redefine? The natural candidates are memory-management functions -- malloc(), free(), new, and delete. Redefining free() and delete to Null operations protects the programmer from premature frees. This leaves only the malloc() and new allocators. But how does this help you identify pointers? A solution to this problem was first observed by Hans Boehm and Mark Weiser. (For more information, see their article, "Garbage Collection In an Uncooperative Environment," Software Practice and Experience, September 1988, as well as Boehm's "Advantages and Disadvantages of Conservative Garbage Collection," at ftp://parcftp.xerox.com/pub/gc/issues.html.) Allocators keep track of what memory has been allocated. You can test whether a data word points inside an allocated object. If so, it's probably a pointer. Is this test always right? No, but it's a start. Sun WorkShop Memory Monitor implements a refined version of this pointer-finding strategy through a custom allocator that can efficiently report on the status of any address. Once you can identify pointers, you can garbage collect a program. We Interrupt this Program... Proper scheduling may be the most important factor in garbage collector performance. The earliest collectors only performed garbage collection when the computer ran out of memory. When a collection finally occurred, it analyzed the computer's entire address memory, interrupting operation for long periods of time. No wonder early garbage collectors were invariably associated with annoying interruptions of program operation. Many current garbage collectors, especially Java collectors, rely primarily on a low-priority background thread to schedule garbage collection. This approach sounds good, but leads to poor performance. The low-priority background thread provides lots of garbage collection to inactive programs that don't need it. By the same token, computation-intensive programs require large amounts of garbage collection, but don't receive any because the background collection thread doesn't have a chance to run since such a program always demands CPU cycles. As a result, background collection threads should, at best, supplement some other primary collection strategy. Sun WorkShop Memory Monitor decides when to collect garbage by watching how much memory has been allocated since the last collection. This way, programs that use lots of dynamic memory allocation receive the collection they need, while programs that don't allocated much memory don't waste a lot of time doing unnecessary garbage collection. To further limit program interruptions, you can do only a small part of the garbage collection each time. At first glance, this seems impossible. The heap is constantly changing, so how can you know that the analysis from earlier partial collections is still correct? Memory-management hardware in the CPU provides some help. After analyzing a page of memory, simply "write-protect" that
C Garbage collector
Documentation excerpt: With Sun WorkShop Memory Monitor, you can program without calling free() or delete. Determining when to call free() or delete is difficult. Studies indicate that 30% to 40% of programmer time is spent on memory management in C or C++ programs. Failing to release memory causes memory leaks, which refers to the accumulation of unused memory in the program, ultimately causing the program to monopolize or even run out of memory. Releasing memory too early leaves loose pointers, which are pointers that do not point to valid memory. Using loose pointers invariably causes data corruption, segmentation faults, or general protection violations. Sun WorkShop Memory Monitor automatically eliminates the problems of freeing memory at the wrong time. In the field, Sun WorkShop Memory Monitor automatically protects your program against memory leaks and premature frees, even those in third-party libraries. Simply linking with Sun WorkShop Memory Monitor automatically eliminates any leaks. In deployment mode, Sun WorkShop Memory Monitor's high-performance memory allocator makes your programs run faster and consume less memory. Sounds like nirvana ;-) Shame it only works with the Sun compilers. However, there is an explanation of how it works that might be useful when considering how to do this for perl6. I've attached the HTML - sorry about the broken links, but I don't think this is on any externally-visible webpage. Alan Burlison
