[svn:modperl-modules] rev 155 - in Apache-Scoreboard-2.0/trunk: Dummy lib/Apache

Author: stas
Date: Sat Feb 26 22:05:37 2005
New Revision: 155

Modified:
   Apache-Scoreboard-2.0/trunk/Dummy/DummyScoreboard.pm
   Apache-Scoreboard-2.0/trunk/lib/Apache/Scoreboard.pm
Log:
improve the docs


Modified: Apache-Scoreboard-2.0/trunk/Dummy/DummyScoreboard.pm
==============================================================================
--- Apache-Scoreboard-2.0/trunk/Dummy/DummyScoreboard.pm	(original)
+++ Apache-Scoreboard-2.0/trunk/Dummy/DummyScoreboard.pm	Sat Feb 26 22:05:37 2005
@@ -12,7 +12,9 @@
 
 =head1 NAME
 
-Apache::DummyScoreboard - Perl interface to the Apache scoreboard structure
+Apache::DummyScoreboard - Perl interface to the Apache scoreboard structure outside mod_perl
+
+
 
 =head1 DESCRIPTION
 
@@ -21,16 +23,29 @@
 the same functionality with some limitations. See the
 C<Apache::Scoreboard> manpage for more info.
 
-=head1 LIMITATIONS
+You shouldn't be using this module directly.
+
+
+
+
+=head1 Limitations
 
 =over
 
-=item *
+=item * C<image>
+
+This method can't be used when not running under Apache/mod_perl. Use
+C<Apache::Scoreboard-E<gt>fetch> instead.
+
+=item * C<Apache::Const::SERVER_LIMIT> and C<Apache::Const::THREAD_LIMIT> 
 
-At the moment C<Apache::Const::SERVER_LIMIT> and
-C<Apache::Const::THREAD_LIMIT> are hardwired to 0, since the methods
-that provide this information are only accessible via a running Apache
-(i.e. via C<Apache::Scoreboad> running under mod_perl).
+At the moment the deprecated constants C<Apache::Const::SERVER_LIMIT>
+and C<Apache::Const::THREAD_LIMIT> are hardwired to 0, since the
+methods that provide this information are only accessible via a
+running Apache (i.e. via C<Apache::Scoreboad> running under mod_perl).
+However, you should be using
+C<L<$image->server_limit|Apache::Scoreboard/C_server_limit_>> and
+C<L<$image->thread_limit|Apache::Scoreboard/C_thread_limit_>>.
 
 =back
 

Modified: Apache-Scoreboard-2.0/trunk/lib/Apache/Scoreboard.pm
==============================================================================
--- Apache-Scoreboard-2.0/trunk/lib/Apache/Scoreboard.pm	(original)
+++ Apache-Scoreboard-2.0/trunk/lib/Apache/Scoreboard.pm	Sat Feb 26 22:05:37 2005
@@ -87,6 +87,10 @@
 
 Apache::Scoreboard - Perl interface to the Apache scoreboard structure
 
+
+
+
+
 =head1 SYNOPSIS
 
   use Apache::Scoreboard ();
@@ -97,6 +101,10 @@
   #outside httpd
   my $image = Apache::Scoreboard->fetch("http://localhost/scoreboard");
 
+
+
+
+
 =head1 DESCRIPTION
 
 Apache keeps track of server activity in a structure known as the
@@ -105,241 +113,263 @@
 served and cpu time.  This same information is used by I<mod_status>
 to provide current server statistics in a human readable form.
 
-=head1 METHODS
 
-=over 4
 
-=item image
+
+=head1 General Methods
+
+
+=head2 C<image>
 
 This method returns an object for accessing the scoreboard structure
 when running inside the server:
 
   my $image = Apache::Scoreboard->image;
 
-=item fetch
+=head2 C<fetch>
 
 This method fetches the scoreboard structure from a remote server,
 which must contain the following configuration:
 
- PerlModule Apache::Scoreboard
- <Location /scoreboard>
-    SetHandler modperl
-    PerlHandler Apache::Scoreboard::send
-    order deny,allow
-    deny from all
-    #same config you have for mod_status
-    allow from 127.0.0.1 ...
- </Location>
+  PerlModule Apache::Scoreboard
+  <Location /scoreboard>
+     SetHandler modperl
+     PerlHandler Apache::Scoreboard::send
+     order deny,allow
+     deny from all
+     #same config you have for mod_status
+     allow from 127.0.0.1 ...
+  </Location>
 
 If the remote server is not configured to use mod_perl or simply for a 
 smaller footprint, see the I<apxs> directory for I<mod_scoreboard_send>:
 
- LoadModule scoreboard_send_module libexec/mod_scoreboard_send.so
-
- <Location /scoreboard>
-    SetHandler scoreboard-send-handler
-    order deny,allow
-    deny from all
-    allow from 127.0.0.1 ...
- </Location>
+  LoadModule scoreboard_send_module libexec/mod_scoreboard_send.so
+  
+  <Location /scoreboard>
+     SetHandler scoreboard-send-handler
+     order deny,allow
+     deny from all
+     allow from 127.0.0.1 ...
+  </Location>
 
 The image can then be fetched via http:
 
   my $image = Apache::Scoreboard->fetch("http://remote-hostname/scoreboard");
 
-=item fetch_store
+=head2 C<fetch_store>
 
-=item retrieve
-
-The I<fetch_store> method is used to fetch the image once from and
-remote server and save it to disk.  The image can then be read by
-other processes with the I<retrieve> function.
-This way, multiple processes can access a remote scoreboard with just
-a single request to the remote server.  Example: 
+see C<L<retrieve()|/C_retrieve_>>
 
- Apache::Scoreboard->fetch_store($url, $local_filename);
+=head2 C<retrieve>
 
- my $image = Apache::Scoreboard->retrieve($local_filename);
+The I<fetch_store> method is used to fetch the image once from a
+remote server and save it to disk.  The image can then be read by
+other processes with the I<retrieve> function.  This way, multiple
+processes can access a remote scoreboard with just a single request to
+the remote server.  Example:
+
+  Apache::Scoreboard->fetch_store($url, $local_filename);
+  
+  my $image = Apache::Scoreboard->retrieve($local_filename);
 
-=item parent_score
+=head2 C<parent_score>
 
 This method returns a reference to the first parent score entry in the 
 list, blessed into the I<Apache::ParentScore> class:
 
- my $parent_score = $image->parent_score;
+  my $parent_score = $image->parent_score;
 
 Iterating over the list of scoreboard slots is done like so:
 
- for (my $parent_score = $image->parent_score;
-      $parent_score;
-      $parent_score = $parent_score->next) {
-     my $pid = $parent_score->pid; #pid of the child
-
-     my $server = $parent_score->server; #Apache::ServerScore object
+  for (my $parent_score = $image->parent_score;
+       $parent_score;
+       $parent_score = $parent_score->next) {
+      my $pid = $parent_score->pid; #pid of the child
+
+      my $server = $parent_score->server; #Apache::ServerScore object
+      ...
+  }
 
-     ...
- }
-
-=item pids
+=head2 C<pids>
 
 Returns an array reference of all child pids:
 
- my $pids = $image->pids;
+  my $pids = $image->pids;
 
 
-=item server_limit
+=head2 C<server_limit>
 
 Returns a server limit for the given image.
 
- my $server_limit = $image->server_limit;
+  my $server_limit = $image->server_limit;
 
 use this instead of the deprecated C<Apache::Const::SERVER_LIMIT>
 constant.
 
 
-=item thread_limit
+=head2 C<thread_limit>
 
 Returns a threads limit per process for the given image.
 
- my $thread_limit = $image->thread_limit;
+  my $thread_limit = $image->thread_limit;
 
 use this instead of the deprecated C<Apache::Const::THREAD_LIMIT>
 constant.
 
 
-=back
 
 
 
 
 
 
-=head2 The Apache::ParentScore Class
 
-=over 4
+=head1 The C<Apache::ParentScore> Class
+
+To get the C<Apache::ParentScore> object use the
+C<L<$image->parent_score()|/C_parent_score_>> or
+C<L<$parent_score->next()|/C_next_>> methods.
 
-=item pid
+=head2 C<pid>
 
 The parent keeps track of child pids with this field:
 
- my $pid = $parent->pid;
+  my $pid = $parent->pid;
 
-=item server
+=head2 C<server>
 
 Returns a reference to the corresponding I<Apache::ServerScore>
 structure:
 
- my $server = $parent->server;
+  my $server = $parent->server;
 
-=item next
+=head2 C<next>
 
 Returns a reference to the next I<Apache::ParentScore> object in the list:
 
- my $p = $parent->next;
+  my $p = $parent->next;
 
-=back
 
-=head2 The Apache::ServerScore Class
 
-=over 4
 
-=item status
+
+
+
+=head1 The C<Apache::ServerScore> Class
+
+To get the C<Apache::ServerScore> object use the
+C<L<$$parent->server()|/C_server_>> method.
+
+=head2 C<status>
 
 This method returns the status of child server, which is one of:
 
- "_" Waiting for Connection
- "S" Starting up
- "R" Reading Request
- "W" Sending Reply
- "K" Keepalive (read)
- "D" DNS Lookup
- "L" Logging
- "G" Gracefully finishing
- "." Open slot with no current process
+  "_" Waiting for Connection
+  "S" Starting up
+  "R" Reading Request
+  "W" Sending Reply
+  "K" Keepalive (read)
+  "D" DNS Lookup
+  "L" Logging
+  "G" Gracefully finishing
+  "." Open slot with no current process
 
-=item access_count
+=head2 C<access_count>
 
 The access count of the child server:
 
- my $count = $server->access_count;
+  my $count = $server->access_count;
 
-=item request
+=head2 C<request>
 
 The first 64 characters of the HTTP request:
 
- #e.g.: GET /scoreboard HTTP/1.0
- my $request = $server->request;
+  #e.g.: GET /scoreboard HTTP/1.0
+  my $request = $server->request;
 
-=item client
+=head2 C<client>
 
 The ip address or hostname of the client:
 
- #e.g.: 127.0.0.1
- my $client = $server->client;
+  #e.g.: 127.0.0.1
+  my $client = $server->client;
 
-=item bytes_served
+=head2 C<bytes_served>
 
 Total number of bytes served by this child:
 
- my $bytes = $server->bytes_served;
+  my $bytes = $server->bytes_served;
 
-=item conn_bytes
+=head2 C<conn_bytes>
 
 Number of bytes served by the last connection in this child:
 
- my $bytes = $server->conn_bytes;
+  my $bytes = $server->conn_bytes;
 
-=item conn_count
+=head2 C<conn_count>
 
 Number of requests served by the last connection in this child:
 
- my $count = $server->conn_count;
+  my $count = $server->conn_count;
 
-=item times
+=head2 C<times>
 
 In a list context, returns a four-element list giving the user and
 system times, in seconds, for this process and the children of this
 process.
 
- my($user, $system, $cuser, $csystem) = $server->times;
+  my($user, $system, $cuser, $csystem) = $server->times;
 
 In a scalar context, returns the overall CPU percentage for this server:
 
- my $cpu = $server->times;
+  my $cpu = $server->times;
 
-=item start_time
+=head2 C<start_time>
 
 In a list context this method returns a 2 element list with the seconds and
 microseconds since the epoch, when the request was started.  In scalar
 context it returns floating seconds like Time::HiRes::time()
 
- my($tv_sec, $tv_usec) = $server->start_time;
+  my($tv_sec, $tv_usec) = $server->start_time;
 
- my $secs = $server->start_time;
+  my $secs = $server->start_time;
 
-=item stop_time
+META: as of Apache 2.0.53 it's yet unavailable (needs to be ported)
+
+=head2 C<stop_time>
 
 In a list context this method returns a 2 element list with the seconds and
 microseconds since the epoch, when the request was finished.  In scalar
 context it returns floating seconds like Time::HiRes::time()
 
- my($tv_sec, $tv_usec) = $server->stop_time;
+  my($tv_sec, $tv_usec) = $server->stop_time;
+
+  my $secs = $server->stop_time;
 
- my $secs = $server->stop_time;
+META: as of Apache 2.0.53 it's yet unavailable (needs to be ported)
 
-=item req_time
+=head2 C<req_time>
 
 Returns the time taken to process the request in microseconds:
 
- my $req_time = $server->req_time;
+  my $req_time = $server->req_time;
 
-=item vhost
+This feature was ported in Apache 2.0.53.
+
+=head2 C<vhost>
 
 Returns the vhost string if there is one.
 
- my $vhost = $server->vhost;
+  my $vhost = $server->vhost;
+
+
+
+
+
+
+
 
-=back
 
 
 =head1 Outside of mod_perl Usage
@@ -348,6 +378,8 @@
 running under mod_perl. It has almost the same functionality with some
 limitations. See the C<Apache::DummyScoreboard> manpage for more info.
 
+
+
 =head1 SEE ALSO
 
 Apache::VMonitor(3), GTop(3)