Re: [AOLSERVER] Sign Up for AOLserver Documentation!
Title: Message What was the new chat time on Thursdays? Last stated was 3pm Eastern, but then you asked for any takers at 2pm Eastern. I abstained, and no one else spoke up, so I'm assuming it was finally changed to 3pm Eastern. I intend to hang out in the chat room all day from now on. /s. -Original Message-From: AOLserver Discussion [mailto:[EMAIL PROTECTED]] On Behalf Of Nathan FolkmanSent: Sunday, November 03, 2002 9:05 PMTo: [EMAIL PROTECTED]Subject: Re: [AOLSERVER] Sign Up for AOLserver Documentation!In a message dated 11/3/02 7:52:51 PM, [EMAIL PROTECTED] writes: After reviewing this, I now see what you're saying. The problem is thatthe second part of some command names should really have been thesubcommand name.For example: ns_returnadminnoticeshould really have been: ns_return adminnoticeIn the same way, ns_sockopenshould really be ns_sock openWere this the case, it would be obvious to look up 'man ns_sock' and'man ns_return'. In these cases, I take back what I said -- I supposethey should be on the same man page.Thus, it appears the AOLserver Tcl Dev Guide is inconsistent --ns_sockopen, ns_socklisten and the other ns_sock* command should havebeen on the same page together, like ns_return*, but they aren't. Maybethat's because the functionality or passed args are essentially the samefor ns_return*, but different for ns_sock*./s.Ironically Jim and I were just discussing changing the nsv_* commands to be something like ns_svar . Keeping the current nsv_* commands for backward compatibility of course! ;-) I think we should concentrate on documenting the files as they exist in $TOP/aolserver/doc and can revisit single vs. multiple commands per file when we turn our attention towards the 4.0 documentation work.- n
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
Title: Message I Agree. We'll do the 3.5 docs first as-is. I think at some point we should bite the bullet and rename commands like ns_returnadminnotice to be ns_return adminnotice and maintain that consistency throughout the server and modules. Backward compatibility would be kept for some period of time. Is there some reason not to rename the 'nsv_*' commands to correspond to Tcl's 'array' command? Thus, 'nsv_set' would change to 'ns_array set', so that ns_array set would correspond to Tcl's array set and so on. Those familiar with Tcl's array command would then intuitively know how to use the nsv_* / ns_array * commands. It might not be a perfect one-to-one correspondence, but it should come pretty close. /s. -Original Message-From: AOLserver Discussion [mailto:[EMAIL PROTECTED]] On Behalf Of Nathan FolkmanSent: Sunday, November 03, 2002 9:05 PMTo: [EMAIL PROTECTED]Subject: Re: [AOLSERVER] Sign Up for AOLserver Documentation!In a message dated 11/3/02 7:52:51 PM, [EMAIL PROTECTED] writes: After reviewing this, I now see what you're saying. The problem is thatthe second part of some command names should really have been thesubcommand name.For example: ns_returnadminnoticeshould really have been: ns_return adminnoticeIn the same way, ns_sockopenshould really be ns_sock openWere this the case, it would be obvious to look up 'man ns_sock' and'man ns_return'. In these cases, I take back what I said -- I supposethey should be on the same man page.Thus, it appears the AOLserver Tcl Dev Guide is inconsistent --ns_sockopen, ns_socklisten and the other ns_sock* command should havebeen on the same page together, like ns_return*, but they aren't. Maybethat's because the functionality or passed args are essentially the samefor ns_return*, but different for ns_sock*./s.Ironically Jim and I were just discussing changing the nsv_* commands to be something like ns_svar . Keeping the current nsv_* commands for backward compatibility of course! ;-) I think we should concentrate on documenting the files as they exist in $TOP/aolserver/doc and can revisit single vs. multiple commands per file when we turn our attention towards the 4.0 documentation work.- n
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
In a message dated 11/3/02 7:52:51 PM, [EMAIL PROTECTED] writes: After reviewing this, I now see what you're saying. The problem is that the second part of some command names should really have been the subcommand name. For example: ns_returnadminnotice should really have been: ns_return adminnotice In the same way, ns_sockopen should really be ns_sock open Were this the case, it would be obvious to look up 'man ns_sock' and 'man ns_return'. In these cases, I take back what I said -- I suppose they should be on the same man page. Thus, it appears the AOLserver Tcl Dev Guide is inconsistent -- ns_sockopen, ns_socklisten and the other ns_sock* command should have been on the same page together, like ns_return*, but they aren't. Maybe that's because the functionality or passed args are essentially the same for ns_return*, but different for ns_sock*. /s. Ironically Jim and I were just discussing changing the nsv_* commands to be something like ns_svar . Keeping the current nsv_* commands for backward compatibility of course! ;-) I think we should concentrate on documenting the files as they exist in $TOP/aolserver/doc and can revisit single vs. multiple commands per file when we turn our attention towards the 4.0 documentation work. - n
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
> I find, for example, that the traditional AOLserver documentation including all > variants of ns_return on a single page helps me to better understand the range > of responses available. After reviewing this, I now see what you're saying. The problem is that the second part of some command names should really have been the subcommand name. For example: ns_returnadminnotice should really have been: ns_return adminnotice In the same way, ns_sockopen should really be ns_sock open Were this the case, it would be obvious to look up 'man ns_sock' and 'man ns_return'. In these cases, I take back what I said -- I suppose they should be on the same man page. Thus, it appears the AOLserver Tcl Dev Guide is inconsistent -- ns_sockopen, ns_socklisten and the other ns_sock* command should have been on the same page together, like ns_return*, but they aren't. Maybe that's because the functionality or passed args are essentially the same for ns_return*, but different for ns_sock*. /s.
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
On Sunday, November 3, 2002, at 02:33 PM, Scott Goodwin wrote: Documenting multiple commands on the same page ... will confuse the readers I disagree; I find, for example, that the traditional AOLserver documentation including all variants of ns_return on a single page helps me to better understand the range of responses available.
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
On Sunday, November 3, 2002, at 02:09 PM, Scott Goodwin wrote: It breaks the unix standard of one command per man page I think Tcl commands are more akin to library calls than shell commands, and there is no standard for a single library call per man page. For examples, look at the documentation for strcpy and friends, or malloc and friends, which have coalesced a number of closely-related calls into a single page in every version of Unix I've used since WiCAT Unix (a System III derivative) in 1983.
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
In a message dated 11/3/02 3:26:08 PM, [EMAIL PROTECTED] writes: Right. The traditional use of man pages is to type in: $ man Such as "man accept" or "man ls" ... and have the accompanying or related call names in the "SEE ALSO" section. I agree with Scott here. -- Dossy I believe both approaches are valid, take the man page for strstr as an example. - n
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
On 2002.11.03, Scott Goodwin <[EMAIL PROTECTED]> wrote: > > If you mean that all the ns_sock* commands are to be documented under > one ns_sock.n man page, I have to disagree. It breaks the unix standard > of one command per man page. I wouldn't know to look in ns_sock.n for > ns_sockopen; the user should not need to know what file a command is > defined in so they can look up the command. And when I want to see how > ns_sockopen works, I don't want ns_socklisten and the others on the same > page. I'd rather have the other related commands be in the "See Also" > section. > > I believe strongly that we should have one man page per API call, and > not one man page per file name. Right. The traditional use of man pages is to type in: $ man Such as "man accept" or "man ls" ... and have the accompanying or related call names in the "SEE ALSO" section. I agree with Scott here. -- Dossy -- Dossy Shiobara mail: [EMAIL PROTECTED] Panoptic Computer Network web: http://www.panoptic.com/ "He realized the fastest way to change is to laugh at your own folly -- then you can let go and quickly move on." (p. 70)
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
Title: Message Not completely true. The Tcl commands are documented on separate man pages -- the 'for' and 'foreach' Tcl commands are on their own separate pages, and the See Also leads you to the other commands. The Tcl C API is a different story -- in this case, the multiple C API functions are documented on the same page. I personally have a difficult time reading through them. I think it will be simpler and easier to write and read the Tcl API commands if we have each command documented separately on its own man page. Documenting multiple commands on the same page will make the man pages that much longer to scroll through, especially if we have good example code on them, and will confuse the readers, especially people new to AOLserver. Even if the confusion is relatively minor, if it can be avoided, I think it should be. Finally, if you look at the AOLserver 3.0 Tcl Dev Guide, each command has its own, separate page that is different for each command (ns_sockopen and ns_socklisten are not the same, repeated page). These are the reasons I believe we should stick with the unix philosophy of "one man page for one command", and continue to follow the way the 3.0 Tcl Dev Guide is done and Tcl commands are done. /s. -Original Message-From: AOLserver Discussion [mailto:[EMAIL PROTECTED]] On Behalf Of Jim DavidsonSent: Sunday, November 03, 2002 1:13 PMTo: [EMAIL PROTECTED]Subject: Re: [AOLSERVER] Sign Up for AOLserver Documentation!In a message dated 11/3/02 2:09:20 PM, [EMAIL PROTECTED] writes: If you mean that all the ns_sock* commands are to be documented under one ns_sock.n man page, I have to disagree. It breaks the unix standard of one command per man page. I wouldn't know to look in ns_sock.n for ns_sockopen; the user should not need to know what file a command is defined in so they can look up the command. And when I want to see how ns_sockopen works, I don't want ns_socklisten and the others on the same page. I'd rather have the other related commands be in the "See Also" section. I believe strongly that we should have one man page per API call, and not one man page per file name. Hi,The AOLserver doc install, like Tcl, includes a mkLinks script which links up all the pages. This means "man ns_sockopen", "man ns_sockaccept", etc. return the same page.-Jim
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
In a message dated 11/3/02 2:09:20 PM, [EMAIL PROTECTED] writes: If you mean that all the ns_sock* commands are to be documented under one ns_sock.n man page, I have to disagree. It breaks the unix standard of one command per man page. I wouldn't know to look in ns_sock.n for ns_sockopen; the user should not need to know what file a command is defined in so they can look up the command. And when I want to see how ns_sockopen works, I don't want ns_socklisten and the others on the same page. I'd rather have the other related commands be in the "See Also" section. I believe strongly that we should have one man page per API call, and not one man page per file name. Hi, The AOLserver doc install, like Tcl, includes a mkLinks script which links up all the pages. This means "man ns_sockopen", "man ns_sockaccept", etc. return the same page. -Jim
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
Title: Message If you mean that all the ns_sock* commands are to be documented under one ns_sock.n man page, I have to disagree. It breaks the unix standard of one command per man page. I wouldn't know to look in ns_sock.n for ns_sockopen; the user should not need to know what file a command is defined in so they can look up the command. And when I want to see how ns_sockopen works, I don't want ns_socklisten and the others on the same page. I'd rather have the other related commands be in the "See Also" section. I believe strongly that we should have one man page per API call, and not one man page per file name. /s. -Original Message-From: AOLserver Discussion [mailto:[EMAIL PROTECTED]] On Behalf Of Nathan FolkmanSent: Saturday, November 02, 2002 9:03 PMTo: [EMAIL PROTECTED]Subject: [AOLSERVER] Sign Up for AOLserver Documentation!To clarify, please sign up by file name instead of by API name. A number of the man pages contain multiple API's - example: $TOP/aolserver/doc/ns_sock.n. Also, please make sure you are working from the aolserver_v35_bp branch. We need to get the docs completed for 3.5, then we will tackle 4.0.To find out what still needs to be documented:1. Check out the 3.5 code: cvs co -raolserver_v35_bp aolserver2. Take a look in $TOP/aolserver/doc for man page files3. Check the "Tasks" area on SourceForge to see what's already been taken4. Add a new task for the man page file, or send email to [EMAIL PROTECTED] or [EMAIL PROTECTED] with the name of the file and we'll add it for youLet me know if there are any questions. Thanks!- n
Re: [AOLSERVER] Use Tcl thread supprt instead of nsthread?
In a message dated 11/2/02 3:49:36 PM, [EMAIL PROTECTED] writes: > - Mutexes in nsthreads have string names and use counters allowing lock > contention monitoring which you can see with "ns_info locks" (very useful). I like this feature of ns_lock because it gives you some insight what is happening in terms of hot-spots in the code. This part would mean rewriting some mutex handling code in Tcl. I'd say, this can be done without adding anything to Tcl. It can be left within the AOLserver as is now. Only the basic lock/unlock/trylock should be delegated to Tcl code. Yes - you could certainly leave the counters in nsthreads and just use the Tcl_Mutexes. However, I think getting the counters in Tcl would be useful - I'm curious about a few locks already, e.g., "preserveMutex" and maybe "obsoleteFsHookMutex". In prior versions of aolserver the roles were reversed, i.e., Tcl sync objects were implemented with nsthreads and locks with highest lock contention (highest but still not alarming) were always buried in the Tcl core. > - There is no Ns_MutexTryLock in Tcl. I do not know why. Both Pthreads and Windows (TryEnterCriticalSection) allow for this. So, why there is no Tcl_MutexTryLock? I don't know. Turns out TryEnterCriticalSection wasn't avail in older Win32 - I can't remember when it arrived but I think it was a service pack to Win2000. The old nsthread win32 code (thread/win32.cpp in the as3.4 source) implemented it's own mutex which wasn't recursive and supported a try lock. BTW: I believe win/tclWinSock.c has a deadlock at line 280 with the extra SocketsEnabled check which is masked by the recursive critical sections so that needs to be fixed as well. I used to patch that code when Tcl 8.3 was distributed with aolserver. > - There is no Ns_Tls interface, instead the > Tcl_GetThreadData/Tcl_CreateThreadExitHandler is used. Looking at tls.c I see no difference to Tcl_GetThreadData, except how the data is released during Tcl_FinalizeThread(). Well, it's true Tcl_GetThreadData calls pthread_key_create but the cleanup callback is always null. I think my last message discussed why I believe this is a more important distinction than it may first appear, in particular the iterative cleanup not only lends itself to cleaner code but in some case (e.g., the Tcl thread allocator) it's a requirement. I believe the people who worked on the pthread spec came to the same conclusion. Note that Win32 Tls doesn't support iterative cleanup but the old nsthreads API implemented it and could be used for Tcl. -Jim
