CVAZ Perl Documentation                                Synch(3)

 

 

 

NAME

     Synch - Manage synchronized resource sharing among

     cooperating processes

 

SYNOPSIS

         # Access to modules (see the NOTES section for setup)

         BEGIN {

             ...

             push (@INC, "../sys/csbase/lib");

         }

 

         use Synch;

 

         # Read access

 

         $readFh = open (...);

         # Coordinate read access - lock out any writers.

         # Returns when we get read access.

         $readSynch = new Synch ($readFh, "r");

           ... read the file ...

         $readSynch->free ();

         close ($readFh);

 

         # Write access - typically used for appending to the file.

 

         $writeFh = open (...);

         # Coordinate write access - lock out any readers and other writers.

         # Returns when we get write access.

         $writeSynch = new Synch ($writeFh, "w");

           ... write the file ...

         $writeSynch->free ();

         close ($writeFh);

 

         # Test for read or write access

 

         $testFh = open (...);

         $testSynch = new Synch ($testFh, "w", 1);

         if ($testSynch->obtainedAccess ()) {

           ... we got access - do some stuff ...

         } else {

           ... failed to get access - kvetch or do something else ...

         }

         $testSynch->free ();

         close ($testFh);

 

 

DESCRIPTION

     This module allows separate processes to coordinate access

     to a shared resource. The module implements a "multiple

     readers OR one writer" algorithm.

 

 

 

 

 

19/Mar/01       Last change: perl 5.004, patch 01               1

 

 

 

 

 

 

CVAZ Perl Documentation                                Synch(3)

 

 

 

     The caller processes must supply a reference to a common

     file on which they agree to cooperatively synchronize. The

     file is be given via an Perl filehandle (opened for

     writing).

 

     NOTE: This package will NOT, repeat NOTTTT, synchronize

     processes running on separate hosts which access the shared

     file over a network. Reliance on the network-ignorant

     flock(2) system call is used.

 

     ANOTHER NOTE: (so you thought this lib was gonna be useful,

     maybe?)  This package is non-reentrant and cannot be

     reliably used in a multi-threaded application.

 

FUNCTIONS

     Synch-

         >new ($underlyingFileHandle, [$accessMode [, $noWait]])

         Create a Synch obj AND issue a sync on the underlying

         file

 

         $fileHandle specifies a file to use for synchronization

         among processes on the same host.

 

         $accessMode is "r" to synchronize for multiple readers

         of a resource.  Writers cannot get access.  $accessMode

         is "w" to synchronize for one writer of a resource.

         Neither Readers nor other Writers cannot get access.

         Default $accessMode is "r".

 

         If $noWait is False (or absent), this constructor does

         not return until access is granted.  If $noWait is True,

         this routine returns (almost) immediately.  A subsequent

         call to the obtainedAccess () method will return 1 if

         access is granted and 0 if the resource is unavailable.

 

     obtainedAccess ()

         Report 1 or 0 as to whether this object currently holds

         the synchronization lock. A zero return can be returned

         if the class constructor was invoked with $noWait set to

         True, or if free() was explicitly called.

 

     free ()

         Relinquish an earlier synchronization.  This method

         typically does not need to be called explicitly, since

         destruction of the object causes the lock to be freed.

 

NOTES

     This module has not yet been set up for "installation" in

     your local Perl. We currently use a set of conventions for

     access to this module, until the install procedures are

     developed:

 

 

 

 

19/Mar/01       Last change: perl 5.004, patch 01               2

 

 

 

 

 

 

CVAZ Perl Documentation                                Synch(3)

 

 

 

     - The source code lives on development and production hosts

     in the directory /Volumes/app/cs/csbase/lib.

 

     - By convention, a project maintains perl scripts in

     subdirectories of some top-level directory, which we will

     call $TOP.

 

     - By convention, projects establish a $TOP/sys directory

     which contains a symbolic link from csbase to

     /Volummes/app/cs/csbase.

 

     - To get access to the modules, you typically include a

     BEGIN of the form:

 

         BEGIN {

             ...

             push (@INC, "../sys/csbase/lib");

         }

 

 

AUTHOR

     Clint Goss <clint@goss.com>, October 1997