* added PODs to all Perl-modules in lib, documenting those functions that are meant

  to be used by other OpenSLX components (i.e. scripts and plugins)
* applied minor cleanups and convenience extensions to a couple of functions

git-svn-id: http://svn.openslx.org/svn/openslx/openslx/trunk@1722 95ad53e4-c205-0410-b2fa-d234c58c8868

1 files changed, 97 insertions, 18 deletions

diff --git a/lib/OpenSLX/ScopedResource.pm b/lib/OpenSLX/ScopedResource.pm
index c905b50a..f278f871 100644
--- a/lib/OpenSLX/ScopedResource.pm
+++ b/lib/OpenSLX/ScopedResource.pm
@@ -8,9 +8,6 @@
 #
 # General information about OpenSLX can be found at http://openslx.org/
 # -----------------------------------------------------------------------------
-# ScopedResource.pm
-#    - a helper class that releases resources if the object leaves scope
-# -----------------------------------------------------------------------------
 package OpenSLX::ScopedResource;
 
 use strict;
@@ -18,12 +15,84 @@ use warnings;
 
 our $VERSION = 1.01;        # API-version . implementation-version
 
+=head1 NAME
+
+OpenSLX::ScopedResource - provides a helper class that implements the 
+'resource-acquisition-by-definition' pattern.
+
+=head1 SYNOPSIS
+
+{   # some scope
+
+    my $distroSession = OpenSLX::ScopedResource->new({
+        name    => 'distro::session',
+        acquire => sub { $distro->startSession(); 1 },
+        release => sub { $distro->finishSession(); 1 },
+    });
+    
+    die $@ if ! eval {
+        # do something dangerous and unpredictable here:
+        doRandomStuff();
+        1;
+    };
+        
+} 
+# the distro-session will be cleanly finished, no matter if we died or not
+
+=head1 DESCRIPTION
+
+The class C<ScopedResource> wraps any resource such that the resource will be
+acquired when an object of this class is created. Whenever the ScopedResource
+object is being destroyed (e.g. by leaving scope) the wrapped resource will
+automatically be released.
+
+The main purpose of this class is to make it simple to implement reliable 
+resource acquisition and release management even if the structure of the code
+that refers to that resource is rather complex. 
+
+Furthermore, this class handles cases where the script handling those resources 
+is spread across different process and/or makes us of signal handlers.
+
+=cut
+
 # make sure that we catch any signals in order to properly released scoped
 # resources
 use sigtrap qw( die normal-signals error-signals );
 
 use OpenSLX::Basics;
 
+=head1 PUBLIC METHODS
+
+=over
+
+=item B<new($params)>
+
+Creates a ScopedResource object for the resource specified by the given 
+I<$params>.
+
+As part of creation of the object, the resource will be acquired.
+
+The I<$params>-hashref requires the following entries:
+
+=over
+
+=item C<name>
+
+Gives a name for the wrapped resource. This is just used in log messages
+concerning the acquisition and release of that resource.
+
+=item C<acuire>
+
+Gives the code that is going to be executed in order to acquire the resource.
+
+=item C<release>
+
+Gives the code that is going to be executed in order to release the resource.
+
+=back
+
+=cut
+
 sub new
 {
     my $class = shift;
@@ -44,12 +113,31 @@ sub new
     
     bless $self, $class;
     
-    $self->acquire();
+    $self->_acquire();
     
     return $self;
 }
 
-sub acquire
+=item B<DESTROY()>
+
+Releases the resource (if it had been acquired by this process) and cleans up.
+
+=cut
+
+sub DESTROY
+{
+    my $self = shift;
+    
+    $self->_release();
+    
+    # remove references to functions, in order to release any closures
+    $self->{acquire} = undef;
+    $self->{release} = undef;
+    
+    return;
+}
+
+sub _acquire
 {
     my $self = shift;
 
@@ -60,7 +148,7 @@ sub acquire
     }
 }
 
-sub release
+sub _release
 {
     my $self = shift;
 
@@ -75,17 +163,8 @@ sub release
     }
 }
 
-sub DESTROY
-{
-    my $self = shift;
-    
-    $self->release();
-    
-    # remove references to functions, in order to release any closures
-    $self->{acquire} = undef;
-    $self->{release} = undef;
-    
-    return;
-}
+=back
+
+=cut
 
 1;