This class is available for the OPUS Blackboard API. The initial OPUS 2.0 release is described here

Constructors:

Opus_lock_file( )
~Opus_lock_file( )

Methods:

assign( )	specify target
lock( )	attempt to lock file
release( )	release lock
operator==( )	compare locks

Description

Opus_lock_file objects perform file locking in OPUS. Given a file to lock, this object creates a special lock file that will cause attempts to lock the same file by other objects to fail. Access to locked files is not controlled, so to maintain file integrity all change access to a file should proceed only after an attempt to obtain a lock with these objects succeeds.

Derived from

Opus_lock

Example

  
    #include <iostream>
    #include "ofile.h"
    #include "opus_lock_file.h"
  
    using namespace std;
  
    // The following example demonstrates the use of lock files
    // in OPUS.
    int main(int argc, char* argv[])
    {
       Ofile of("DATA_DIR:data1.txt");    // existing file!
       Opus_lock_file* lock = 0;
       try {
          lock = new Opus_lock_file(of);  // create lock object
          lock->lock();                   // attempt lock
       }
       catch(...) {
          cerr << "Lock attempt failed." << endl;
       }
       delete lock;                       // release lock & delete object
       return(0);
    }
  

See Also:

• Opus_lock
• "OPUS API Blackboard and Support Classes Design Document"

Opus_lock_file::Opus_lock_file - The Opus_lock_file object constructor.

Synopsis

Opus_lock_file::Opus_lock_file()

Opus_lock_file::Opus_lock_file(
                               const string& fname) // I - file name

Opus_lock_file::Opus_lock_file(
                               const File_entry* fe) // I - file name

Opus_lock_file::Opus_lock_file(
                               const Ofile& of) // I - file name

Description

This method assigns the target name, if provided, then generates the lock file name.

Exceptions Thrown

Bad_val<string>	- if the string does not appear to be a directory specification or invalid characters are present; Bad_val.arg contains the calling argument
Io_error<int>	- if a problem occurs determining the current working directory; Io_error.arg contains the value of errno
Bad_val<string>	- if the string contains invalid characters; Bad_val.arg contains the calling argument
Bad_val<string>	- if the extension prefix is not present or invalid characters are present; Bad_val.arg contains the calling argument
Bad_val<string>	- if dangle prefix is not present or invalid characters are present; Bad_val.arg contains the calling argument
Io_error<int>	- if an IO error occurs creation of the lock directory; Io_error.arg contains the value of errno

Opus_lock_file::~Opus_lock_file - The Opus_lock_file object destructor.

Synopsis

Opus_lock_file::~Opus_lock_file()

Description

This method releases the lock (if locked), then destroys the object.

Exceptions Thrown

none

Opus_lock_file::lock - Attempt to lock the file.

Synopsis

void Opus_lock_file::lock()

void Opus_lock_file::lock(
                          const string& s) // I - file to lock

void Opus_lock_file::lock(
                          const File_entry* fe) // I - file to lock

void Opus_lock_file::lock(
                          const Ofile& of) // I - file to lock

Description

An attempt is made to lock the target up to three times when this method is called.

Exceptions Thrown

Locked<string>	- if the target file is locked already; Locked.arg contains the target name
Io_error<int>	- if an IO error occurs during the lock attempt; Io_error.arg contains the value of errno
Bad_val<string>	- if the stretch cannot be resolved; Bad_val.arg contains the stretched file name
Bad_val<vector<string>>	- if the calling arguments are incorrect; Bad_val.arg is a vector containing the calling arguments
Io_error<int>	- if the disk space check fails; Io_error.arg contains the value of errno
Bad_val<vector<string>>	- if calling arguments are incorrect; Bad_val.arg is a vector containing the calling arguments
Exec<int>	- if the subprocess spawn attempt fails; Exec.arg contains the return status from the spawn attemp
Bad_val<string>	- if the string does not appear to be a directory specification or invalid characters are present; Bad_val.arg contains the calling argument
Io_error<int>	- if a problem occurs determining the current working directory; Io_error.arg contains the value of errno
Bad_val<string>	- if the string contains invalid characters; Bad_val.arg contains the calling argument
Bad_val<string>	- if the extension prefix is not present or invalid characters are present; Bad_val.arg contains the calling argument
Bad_val<string>	- if dangle prefix is not present or invalid characters are present; Bad_val.arg contains the calling argument
Io_error<int>	- if an IO error occurs creation of the lock directory; Io_error.arg contains the value of errno

Opus_lock_file::assign - Set the target of the lock.

Synopsis

void Opus_lock_file::assign(
                            const string& s) // I - target

void Opus_lock_file::assign(
                            const File_entry* fe) // I - target

void Opus_lock_file::assign(
                            const Ofile& of) // I - target

Description

This method sets the target of this object and generates the lock name.

Exceptions Thrown

Bad_val<string>	- if the string does not appear to be a directory specification or invalid characters are present; Bad_val.arg contains the calling argument
Io_error<int>	- if a problem occurs determining the current working directory; Io_error.arg contains the value of errno
Bad_val<string>	- if the string contains invalid characters; Bad_val.arg contains the calling argument
Bad_val<string>	- if the extension prefix is not present or invalid characters are present; Bad_val.arg contains the calling argument
Bad_val<string>	- if dangle prefix is not present or invalid characters are present; Bad_val.arg contains the calling argument
Io_error<int>	- if an IO error occurs creation of the lock directory; Io_error.arg contains the value of errno

Opus_lock_file::release - Release lock on file.

Synopsis

void Opus_lock_file::release()

Description

This method deletes the lock file (if present and the object is locked).

Exceptions Thrown

Io_error<int>

- if an IO error occurs during delete; Io_error.arg contains the value of errno

Opus_lock_file::operator== - Equality test for Opus_lock_file objects.

Synopsis

bool Opus_lock_file::operator==(
                                const Opus_lock* ol) // I - lock to compare
                                const

Description

This method compares an Opus_lock_file object to this object. Equality is based on their lock file names: if they match, the locks are considered equal.

Returns

    true  - if the locks are identical
    false - if the locks do not match

Exceptions Thrown

none

For more information, contact opushelp@stsci.edu

Last modified: 25 April 2000