NCCI 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

NCCI 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

NCCI 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