Documentation Project
Greetings, I have a few questions after having been subscribed to this list for a few days. 1) I see that there's not a lot of activity on this list. What is the current active status of the project? 2) I notice that there is a database interface, but even though SQLite is supported, the exposed APIs resemble DBM-style interfaces. Is there a plan to create a super-simple rowset style interface for backends that support it? 3) The documentation is scarce or non-existent. Everything I've learned thus far has been from Inoue Seiichiro's tutorial. Are there any official documentation project's active or planned? I'm currently using APR for a commercial router project, and am learning as I go. I'm rather impressed with the elegance and clean use of incomplete types for a more, dare I say it, 'object oriented' approach to C APIs. If there is no documentation project currently active, I can attempt to document what I'm learning as I go, and donate it back to the project. Thanks, Tom -- Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
On Mon, 24 Apr 2006 15:12:58 -0400 Tom Bradford [EMAIL PROTECTED] wrote: Greetings, I have a few questions after having been subscribed to this list for a few days. 1) I see that there's not a lot of activity on this list. What is the current active status of the project? Hint: http://www.apache.org/dist/apr/ [CHANGES*] 2) I notice that there is a database interface, but even though SQLite is supported, the exposed APIs resemble DBM-style interfaces. Is there a plan to create a super-simple rowset style interface for backends that support it? I don't know, what does Google say ? 3) The documentation is scarce or non-existent. Everything I've learned thus far has been from Inoue Seiichiro's tutorial. Are there any official documentation project's active or planned? http://apr.apache.org/docs/apr/modules.html http://apr.apache.org/apr2_0intro/apr2_0intro.htm I'm currently using APR for a commercial router project, and am learning as I go. I'm rather impressed with the elegance and clean use of incomplete types for a more, dare I say it, 'object oriented' approach to C APIs. If there is no documentation project currently active, I can attempt to document what I'm learning as I go, and donate it back to the project. -- Davi Arnaut
Re: Documentation Project
On Apr 24, 2006, at 3:54 PM, Davi Arnaut wrote: 2) I notice that there is a database interface, but even though SQLite is supported, the exposed APIs resemble DBM-style interfaces. Is there a plan to create a super-simple rowset style interface for backends that support it? I don't know, what does Google say ? Well, I was hoping that an actual representative of the project could speak to what is planned for the project proper, rather than try to infer what may or may not be happening to the project at some point in the future. 3) The documentation is scarce or non-existent. Everything I've learned thus far has been from Inoue Seiichiro's tutorial. Are there any official documentation project's active or planned? http://apr.apache.org/docs/apr/modules.html http://apr.apache.org/apr2_0intro/apr2_0intro.htm Sorry, but Doxygen and a slideshow with little to no actual information (both of which I've already seen) do not a suite of documentation make. Doxygen is as valuable in the grand scheme of things as is Javadoc, and that's not much because neither are able to paint an overall picture of contextual or global cohesion. As I was saying, Inoue Seiichiro's tutorial is by the far the best documentation I've found for APR, and the fact that nothing made available by the APR project itself even comes close is somewhat disconcerting. Let me reiterate. I'm very impressed with the API, and I see broad developmental usage for APR outside of the Apache project proper, but the major hurdle at this point is the very real lack of documentation. Not need to get defensive about it, especially since I'm offering my assistance. -- Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
Tom Bradford wrote: Greetings, I have a few questions after having been subscribed to this list for a few days. 1) I see that there's not a lot of activity on this list. What is the current active status of the project? apr tends to grow in fits and spurts. So you may see the list quite quiet for a time (-especially- when alot of the main contributors are hiding over at httpd, svn or other projects trying to get to some end goal). On the other hand, prepare for 20-30 mail deluge some afternoon, you've been warned :) 3) The documentation is scarce or non-existent. Everything I've learned thus far has been from Inoue Seiichiro's tutorial. Are there any official documentation project's active or planned? The documentation can -certainly- use improvement, mostly from the perspective of 'new to apr, how do I get started?' along with some of the more cryptic bits of collective knowledge. I'm currently using APR for a commercial router project, and am learning as I go. I'm rather impressed with the elegance and clean use of incomplete types for a more, dare I say it, 'object oriented' approach to C APIs. Glad to hear it looks suited to your project! If there is no documentation project currently active, I can attempt to document what I'm learning as I go, and donate it back to the project. Documentation discussions do belong on [EMAIL PROTECTED], since the docs need the eyeballs of the authors who designed the interfaces. Thank you for the offer, as all contributions, code, docs, beer are welcome. Bill
Re: Documentation Project
On 4/24/06, Tom Bradford [EMAIL PROTECTED] wrote: Greetings, I have a few questions after having been subscribed to this list for a few days. 1) I see that there's not a lot of activity on this list. What is the current active status of the project? As others have said, it varies. 2) I notice that there is a database interface, but even though SQLite is supported, the exposed APIs resemble DBM-style interfaces. Is there a plan to create a super-simple rowset style interface for backends that support it? Umm, what do you mean by DBM-style? The dbd stuff doesn't seem very similar to DBM apis to me. If you have alternate APIs you'd like to see feel free to propose them on this list. 3) The documentation is scarce or non-existent. Everything I've learned thus far has been from Inoue Seiichiro's tutorial. Are there any official documentation project's active or planned? I'm currently using APR for a commercial router project, and am learning as I go. I'm rather impressed with the elegance and clean use of incomplete types for a more, dare I say it, 'object oriented' approach to C APIs. If there is no documentation project currently active, I can attempt to document what I'm learning as I go, and donate it back to the project. Personally, I'd love to see more complete documentation, either via patches to the existing doxygen or separate docs outside the source code. -garrett
Re: Documentation Project
On Mon, 24 Apr 2006 16:13:38 -0400 Tom Bradford [EMAIL PROTECTED] wrote: On Apr 24, 2006, at 3:54 PM, Davi Arnaut wrote: 2) I notice that there is a database interface, but even though SQLite is supported, the exposed APIs resemble DBM-style interfaces. Is there a plan to create a super-simple rowset style interface for backends that support it? I don't know, what does Google say ? Well, I was hoping that an actual representative of the project could speak to what is planned for the project proper, rather than try to infer what may or may not be happening to the project at some point in the future. 3) The documentation is scarce or non-existent. Everything I've learned thus far has been from Inoue Seiichiro's tutorial. Are there any official documentation project's active or planned? http://apr.apache.org/docs/apr/modules.html http://apr.apache.org/apr2_0intro/apr2_0intro.htm Sorry, but Doxygen and a slideshow with little to no actual information (both of which I've already seen) do not a suite of documentation make. Doxygen is as valuable in the grand scheme of things as is Javadoc, and that's not much because neither are able to paint an overall picture of contextual or global cohesion. As I was saying, Inoue Seiichiro's tutorial is by the far the best documentation I've found for APR, and the fact that nothing made available by the APR project itself even comes close is somewhat disconcerting. IMHO, Inoue Seiichiro's tutorial goes out of scope (eg, describing what a thread is, et cetera). What kind of documentation you're most interested in ? Guides, how-to, tutorial.. Let me reiterate. I' very impressed with the API, and I see broad developmental usage for APR outside of the Apache project proper, but the major hurdle at this point is the very real lack of documentation. Not need to get defensive about it, especially since I'm offering my assistance. Fair enough. Welcome aboard. -- Davi Arnaut
Re: Documentation Project
On Apr 24, 2006, at 4:27 PM, William A. Rowe, Jr. wrote: Documentation discussions do belong on [EMAIL PROTECTED], since the docs need the eyeballs of the authors who designed the interfaces. Thank you for the offer, as all contributions, code, docs, beer are welcome. Very good. I'll work on areas as I'm utilizing them in my own projects, so things may tend to be sporadic initially, but I'll try to ties things together as I completion sections. Effectively, what I'd like to see result from my efforts is a piece of work similar to 'APR in a Nutshell', where major areas of the system are discussed from an introductory standpoint, and they are backed up by fleshing out the doxygen code more thoroughly. -- Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
On Apr 24, 2006, at 4:54 PM, Davi Arnaut wrote: IMHO, Inoue Seiichiro's tutorial goes out of scope (eg, describing what a thread is, et cetera). What kind of documentation you're most interested in ? Guides, how-to, tutorial.. Describing what a thread is, how a socket works, etc, are all part of a greater whole wherein you give a reader a proper context in which to work and learn. Presenting a threading API to someone who doesn't know the fundamentals of threads provides absolutely no value. On the other hand, providing a few extra paragraphs to serve as a foundation for the simplified threading APIs that one is about to learn goes a long way toward 'selling' your project to a much broader audience. For example... reading the doxygen docs, I saw the words 'bucket brigade', and my first inclination is to ask 'what the hell is a bucket brigade?'. I knew what a bucket it is, but my understanding of a bucket was from a very broad perspective, so giving a foundation for these things rather than the pure technical mumbo-jumbo will afford you a much larger audience by reducing the learning curve, which in my experience (partly with Apache Xindice, but also with other projects) is a major stopping point for projects such as these. Maximum return for minimal investment. -- Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
On Apr 24, 2006, at 4:47 PM, Garrett Rooney wrote: Umm, what do you mean by DBM-style? The dbd stuff doesn't seem very similar to DBM apis to me. If you have alternate APIs you'd like to see feel free to propose them on this list. By DBM-style, I mean you're effectively talking about the storage of key/value pairs where the atom representation of a value is effectively a void pointer, rather than tuples, which is how SQLite and other RDBMS' inherently operate. I have no ideas off the top of my head, but I will be using both SQLite and APR in this project, so I may come up with something as it moves forward. -- Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
On Mon, 2006-04-24 at 16:13 -0400, Tom Bradford wrote: Sorry, but Doxygen and a slideshow with little to no actual information (both of which I've already seen) do not a suite of documentation make.Doxygen is as valuable in the grand scheme of things as is Javadoc, and that's not much because neither are able to paint an overall picture of contextual or global cohesion. Actually, pages like this: http://apr.apache.org/docs/apr/ should contain the glue you're looking for. Probably the most straightforward thing to do is to write up plain text files and include them verbatim on this page during doc generation, like this: http://httpd.apache.org/apreq/docs/libapreq2/ but a lot more detailed, of course. Doxygen can be bent to deliver not just API documentation, but also any other document we want to put in it. The benefit would be obvious - potential, novice and expert users can use one and only documentation system for APR/APU, from tutorials, philosophy and organisation to a full API reference. But I do get your point. I found myself that many times I wasn't quite clear on how things were supposed to hang together in APR/APU and the only way to really find out was to look at the source. -- Bojan
Re: Documentation Project
On 4/24/06, Tom Bradford [EMAIL PROTECTED] wrote: On Apr 24, 2006, at 4:47 PM, Garrett Rooney wrote: Umm, what do you mean by DBM-style? The dbd stuff doesn't seem very similar to DBM apis to me. If you have alternate APIs you'd like to see feel free to propose them on this list. By DBM-style, I mean you're effectively talking about the storage of key/value pairs where the atom representation of a value is effectively a void pointer, rather than tuples, which is how SQLite and other RDBMS' inherently operate. Umm, have you looked at apr_dbd.h? It doesn't return void pointers to you at all, it returns result and row structures, which you can retrieve data out of via various functions. apr_dbm.h is very DBM like, but that's a totally different API and has nothing to do with sqlite (or any sql database for that matter). -garrett
Re: Documentation Project
On Mon, 2006-04-24 at 17:07 -0400, Tom Bradford wrote: By DBM-style, I mean you're effectively talking about the storage of key/value pairs where the atom representation of a value is effectively a void pointer, rather than tuples, which is how SQLite and other RDBMS' inherently operate. I think you're probably reading DBM docs and thinking of DBD - something that was recently fixed (i.e. DBD documentation was not generated for some versions of APU). The actual DBD support for SQLite2/3 is SQL orientated (i.e. you do things like select/query and then fetch rows/values). This should be fixed in the future Doxygen docs. However, we should mention that DBD uses APU style SQL (yes, there is such a thing :-), where in prepared statements %s, %d and similar are used in place of $1, $2 (PGSQL) or ? (MySQL) parameters to make them uniform across database types. In fact I should probably document this :-( -- Bojan
hey, I use apr!
I just noticed the 'open source projects using APR' section... feel free to add me to the list :-) mod_bt / libbtt http://www.crackerjack.net/mod_bt/ - Tyler
Re: hey, I use apr!
On 4/24/06, Tyler MacDonald [EMAIL PROTECTED] wrote: I just noticed the 'open source projects using APR' section... feel free to add me to the list :-) mod_bt / libbtt http://www.crackerjack.net/mod_bt/ Send in a patch to the website and I'd be happy to apply it. -garrett
Re: Documentation Project
On Monday 24 April 2006 20:12, Tom Bradford wrote: Greetings, I have a few questions after having been subscribed to this list for a few days. 1) I see that there's not a lot of activity on this list. What is the current active status of the project? Activity is variable. Check the archives. 2) I notice that there is a database interface, but even though SQLite is supported, the exposed APIs resemble DBM-style interfaces. Is there a plan to create a super-simple rowset style interface for backends that support it? Not sure what you mean there? 3) The documentation is scarce or non-existent. Everything I've learned thus far has been from Inoue Seiichiro's tutorial. Are there any official documentation project's active or planned? That tutorial is probably the only one of its kind. There are some more at www.apachetutor.org, but they are oriented to the webserver (though the pools one at least is just as relevant to the APR in its own right). My book (tba) has a complete chapter on the APR. Coincidentally, I've just written an article about the APR. It's an overview rather than a tutorial or documentation, but may be of interest. If there is no documentation project currently active, I can attempt to document what I'm learning as I go, and donate it back to the project. Great! There's ample scope for new documentation that duplicates neither the API docs nor the existing tutorials. Now, why don't we have any mention of it on the APR pages? At the very least, a link to Inoue Seiichiro would be in order. -- Nick Kew
Re: hey, I use apr!
Garrett Rooney [EMAIL PROTECTED] wrote: On 4/24/06, Tyler MacDonald [EMAIL PROTECTED] wrote: I just noticed the 'open source projects using APR' section... feel free to add me to the list :-) mod_bt / libbtt http://www.crackerjack.net/mod_bt/ Send in a patch to the website and I'd be happy to apply it. Sure, those pages look templated though, where does the source live? Thanks, Tyler
Re: hey, I use apr!
On 4/24/06, Tyler MacDonald [EMAIL PROTECTED] wrote: Garrett Rooney [EMAIL PROTECTED] wrote: On 4/24/06, Tyler MacDonald [EMAIL PROTECTED] wrote: I just noticed the 'open source projects using APR' section... feel free to add me to the list :-) mod_bt / libbtt http://www.crackerjack.net/mod_bt/ Send in a patch to the website and I'd be happy to apply it. Sure, those pages look templated though, where does the source live? http://svn.apache.org/repos/asf/apr/site/trunk/ The templates live under xdocs, and the generated site goes under docs. -garrett
Re: hey, I use apr!
On Monday 24 April 2006 22:22, Tyler MacDonald wrote: I just noticed the 'open source projects using APR' section... feel free to add me to the list :-) mod_bt / libbtt http://www.crackerjack.net/mod_bt/ But isn't that an apache module? So that makes use of APR pretty much automatic, as in all other modules. Should we really be adding them as separate entities? -- Nick Kew
Re: Documentation Project
On Apr 24, 2006, at 5:17 PM, Bojan Smojver wrote: On Mon, 2006-04-24 at 17:07 -0400, Tom Bradford wrote: By DBM-style, I mean you're effectively talking about the storage of key/value pairs where the atom representation of a value is effectively a void pointer, rather than tuples, which is how SQLite and other RDBMS' inherently operate. I think you're probably reading DBM docs and thinking of DBD - something that was recently fixed (i.e. DBD documentation was not generated for some versions of APU). The actual DBD support for SQLite2/3 is SQL orientated (i.e. you do things like select/query and then fetch rows/values). This should be fixed in the future Doxygen docs. Yes, this looks like the case from the generated docs that I have. I tend to look at the docs first as the clearing house of all knowledge for a package, as having to investigate others' source can be a potentially harrowing experience. -- Tom Bradford - http://www.tbradford.org/
Re: hey, I use apr!
On 4/24/06, Nick Kew [EMAIL PROTECTED] wrote: On Monday 24 April 2006 22:22, Tyler MacDonald wrote: I just noticed the 'open source projects using APR' section... feel free to add me to the list :-) mod_bt / libbtt http://www.crackerjack.net/mod_bt/ But isn't that an apache module? So that makes use of APR pretty much automatic, as in all other modules. Should we really be adding them as separate entities? That occurred to me, but it also appears that libbtt is a separate library, which is more interesting. -garrett
Re: hey, I use apr!
Garrett Rooney [EMAIL PROTECTED] wrote: On 4/24/06, Tyler MacDonald [EMAIL PROTECTED] wrote: Garrett Rooney [EMAIL PROTECTED] wrote: On 4/24/06, Tyler MacDonald [EMAIL PROTECTED] wrote: I just noticed the 'open source projects using APR' section... feel free to add me to the list :-) mod_bt / libbtt http://www.crackerjack.net/mod_bt/ Send in a patch to the website and I'd be happy to apply it. Sure, those pages look templated though, where does the source live? http://svn.apache.org/repos/asf/apr/site/trunk/ OK, here it is! Thanks, Tyler Index: projects.xml === --- projects.xml(revision 396705) +++ projects.xml(working copy) @@ -28,6 +28,7 @@ mod_jk v2 and mod_webapp/a (part of Tomcat)/li lia href=http://www.rexursive.com/software/modspin/;mod_spin/a/li lia href=http://subversion.tigris.org/;Subversion/a/li + lia href=http://www.crackerjack.net/mod_bt/;libbtt/a (part of mod_bt)/li /ul /section
Fwd: Re: hey, I use apr!
I've *got* to stop sending mail out from the wrong address... bad tyler! ---BeginMessage--- Nick Kew [EMAIL PROTECTED] wrote: On Monday 24 April 2006 22:22, Tyler MacDonald wrote: I just noticed the 'open source projects using APR' section... feel free to add me to the list :-) mod_bt / libbtt http://www.crackerjack.net/mod_bt/ But isn't that an apache module? So that makes use of APR pretty much automatic, as in all other modules. Should we really be adding them as separate entities? mod_bt itself is, but libbtt isn't. It's a generalized BitTorrent Tracker logic library. Here's an example script that doesn't use apache itself: http://www.crackerjack.net/mod_bt/bttrack.pl.txt Also check out bt_db2xml.c in the source tarball. Ugh, and I just realized i need to fix bttrack.pl... the use Apache2 line is a remnant from when you needed to do that to add the path to APR.pm to perl's @INC, which is no longer neccessary... At least it's only an example :-/ - Tyler ---End Message---
Re: hey, I use apr!
On 4/24/06, Tyler MacDonald [EMAIL PROTECTED] wrote: OK, here it is! Committed and pushed to the live site, thanks! -garrett
RFC: graceful handling of abandoned shared memory
This patch makes dealing with SysV IPC shared memory a bit easier:
- If a shared memory segment exists with the key that you want, a
check is performed to see if anybody else is using it. If not, then it's
assumed that the segment is a result of an unclean shutdown of a process,
and we attach to that segment instead of creating our own new one.
This patch still requires that the file that the named memory segment is
bound to does not exist, but it *does* ensure that if the file is removed,
you can usually get your memory segment back and your program won't fail to
start up because of a poor choice in shared memory implementation. ;-) This
brings the SysV IPC shmem stuff in APR a lot closer to behaving the same as
the mmap() implementation. Please let me know what you think.
Cheers,
Tyler
Index: shmem/unix/shm.c
===
--- shmem/unix/shm.c(revision 396689)
+++ shmem/unix/shm.c(working copy)
@@ -315,7 +315,26 @@
if ((new_m-shmid = shmget(shmkey, new_m-realsize,
SHM_R | SHM_W | IPC_CREAT | IPC_EXCL)) 0)
{
-return errno;
+if(errno == EEXIST) {
+/* if the segment already exists, check to see if
+ * anybody is attached to it. if not, we should still
+ * use it; this keeps us in sync with the behaviour of
+ * other implementations (mmap etc)
+ */
+if((new_m-shmid = shmget(shmkey, new_m-realsize,
+SHM_R | SHM_W)) 0) {
+return errno;
+} else {
+if (shmctl(new_m-shmid, IPC_STAT, shmbuf) == -1) {
+return errno;
+}
+if(shmbuf.shm_nattch 0) {
+return EEXIST;
+}
+}
+} else {
+return errno;
+}
}
if ((new_m-base = shmat(new_m-shmid, NULL, 0)) == (void *)-1) {
@@ -593,5 +612,4 @@
apr_pool_t *pool)
{
return APR_ENOTIMPL;
-}
-
+}
