Table of Contents

Class: GassCache ./pyGlobus/gassCache.py

Provides an interface to the gass cache module.

Allows the manipulation of local cache files. Each cache entry can be locked during addition and deletion, to allow for atomic handling of the cache file contents.

Each cache entry also has an associated timestamp. This timestamp is independent of the local cache file's modification time. Rather, the cache entry timestamp is maintained by the user. It can, for example, be used to keep track of the timestamp of a remote file that is associate with a cache entry.

Note: All timestamps are as seconds since the epoch. (01 Jan 1970, 00:00 GMT)

Methods   
__del__
__init__
add
add_done
cleanup_file
cleanup_tag
close
delete
delete_start
list
open
  __del__ 
__del__ ( self )

Destroy an instance.

Deactivates the underlying module. Before deleting the module, close should be called once for each open call.

Raises:

A GassCacheException is thrown if unable to deactivate the module.

Exceptions   
ex
  __init__ 
__init__ ( self )

Constructs an instance.

Activates the underlying globus gass cache module.

Raises:

A GassCacheException is thrown if unable to initialize the module, or open the cache.

Exceptions   
ex
  add 
add (
        self,
        url,
        tag=None,
        create=1,
        )

Add a URL to the cache.

If the URL is already in the cache but is locked, then then this call will block until the cache entry is unlocked, then will proceed with the subsequent operations.

If the URL is already in the cache and unlocked, then add the tag to the cache entry's tag list, return the local cache filename, return the entry's current timestamp in *timestamp, lock the cache entry, and return GLOBUS_GASS_CACHE_ADD_EXISTS.

If the URL is not in the cache, and create is true, then create a new unique empty local cache file, add it to the cache with the specified tag, return the filename in local_filename, return timestamp set to GLOBUS_GASS_TIMESTAMP_UNKNOWN, lock the cache entry, and return GLOBUS_GASS_CACHE_ADD_NEW. If the URL is not in the cache, and create is false, then do not add it to the cache, and return GLOBUS_GASS_CACHE_URL_NOT_FOUND.

If this function returns GLOBUS_GASS_CACHE_ADD_EXISTS or GLOBUS_GASS_CACHE_ADD_NEW, then globus_gass_cache_add_done() or globus_gass_cache_delete() must be subsequently called to unlock the cache entry.

Subsequent calls to globus_gass_cache_add() and globus_gass_cache_delete_start() on the same cache and url, made either from this process or another, will block until the cache entry is unlocked. If tag == None, then a tag with the value null will be added to the cache entry's tag list.

The same tag can be used multiple times, in which case this tag will be added to the entry's tag list multiple times.

Note: It is recommended that programs started via GRAM pass a tag value of getenv(GRAM_JOB_CONTACT), since upon completion of a job GRAM will automatically cleanup entries with this tag.

Arguments:

  • url * url of the file to be cached. It is used as the main key to the cache entries.

  • tag tag specifying which job is using the cache. This is usually the GRAM_JOB_CONTACT. If it is None, a tag of NULL is used.

  • create tells if the cache should be created, if it does not already exist.

Raises:

A GassCacheException is thrown if an error occurs while adding the url to the cache.

Returns

A tuple containing the error code, one of GLOBUS_SUCCES, GLOBUS_GASS_CACHE_URL_NOT_FOUND, GLOBUS_GASS_CACHE_ADD_NEW, GLOBUS_GASS_CACHE_ADD_EXISTS. The ime stamp of the cached file, set by add_done(), or delete(). The local filename in the local filesystem caching the file specified by the url. NULL if the "url" is not yet cached, and creation isn't requested. (create false)

Exceptions   
GassCacheException(gassCachec.globus_gass_cache_error_string( ret ) )
  add_done 
add_done (
        self,
        url,
        tag,
        timestamp,
        )

Set the timestamp in the cache entry for the URL, and then unlock the cache entry.

globus_gass_cache_add_done() MUST be called after globus_gass_cache_add(), to set the timestamp in the cache entry for the URL, and then unlock the cache entry. (The only case it does not need to be called is if globus_gass_cache_add() has returned GLOBUS_GASS_CACHE_URL_NOT_FOUND, of course.

Arguments:

  • url * url of the cached file to set as done (unlock).

  • tag * tag specifying which job has locked the cache and must therefore be unlocked. It is an error to call this function with a tag which does not currently own the cache lock.

  • timestamp time stamp of the cached file

Raises:

A GassCacheException is thrown if an error occurs while unlocking the chache entry.

Exceptions   
GassCacheException(gassCachec.globus_gass_cache_error_string( ret ) )
  cleanup_file 
cleanup_file ( self,  url )

Cleanup the given cache entry.

Remove the cache entry and delete the associated local cache file, regardless of the tags in tag list, and regardless of whether or not the cache entry is locked.

Arguments:

  • url url of the cached file to cleanup.

Raises:

A GassCacheException is thrown if an error occurs while cleaning up the cache entry.

Exceptions   
GassCacheException(gassCachec.globus_gass_cache_error_string( ret ) )
  cleanup_tag 
cleanup_tag (
        self,
        url,
        tag,
        )

Remove the given tag from the cache table.

Remove all instances of the tag from the cache entry's tag list. If there are no more tags in the tag list, then remove this cache entry and delete the associated local cache file.

If the cache entry is locked with the same tag as is passed to this function, then the entry is unlocked after removing the tags. Otherwise, the cache entry's lock is left untouched.

Note: The GRAM job manager will automatically call this function with a tag of getenv(GRAM_JOB_CONTACT) upon completion of a job.

Arguments:

  • url * url of the cached file to set as done (unlock).

  • tag tag specifying which job is using the cache. This is usually the GRAM_JOB_CONTACT. It can be None or empty; the tag null is then used.

Raises:

A GassCacheException is thrown if an error occurs while cleaning up the tag entry.

Exceptions   
GassCacheException(gassCachec.globus_gass_cache_error_string( ret ) )
  close 
close ( self )

Close the given cache.

Raises:

A GassCacheException is thrown if unable to close the cache.

Exceptions   
ex
  delete 
delete (
        self,
        url,
        tag,
        timestamp,
        isLocked,
        )

Delete a tag entry from the cache.

Remove one instance of the tag from the cache entry's tag list. If there are no more tags in the tag list, then remove this cache entry and delete the associated local cache file. Otherwise, update the timestamp to the passed value.

If is_locked==GLOBUS_TRUE, then this cache entry was locked during a previous call to add() or globus_gass_cache_delete_start(). Otherwise, the entry will be locked at the start of this operation.

This call will leave the cache entry unlocked.

Arguments:

  • url * url of the cached file to set as done (unlock).

  • tag * tag specifying which job is using the cache. This is usually the GRAM_JOB_CONTACT. It can be None or empty; the tag null is then used.

  • isLocked Indicates if this cached entry was locked during a previous call to add() or delete_start()

Raises:

A GassCacheException is thrown if an error occurs while deleting the chache entry.

Exceptions   
GassCacheException(gassCachec.globus_gass_cache_error_string( ret ) )
  delete_start 
delete_start (
        self,
        url,
        tag,
        )

Lock the cache entry prior to deleting it.

Lock the cache entry for the URL, and return the cache entry's current timestamp in *timestamp.

Arguments:

  • url * url of the cached file to set as "done" (unlock).

  • tag tag specifying which job has locked the cache and must therefore be unlocked. It is an error to call this function with a tag which does not currently own the cache lock. Raises:

A GassCacheException is thrown if an error occurs while locking the chache entry.

Returns:

Returns the timestamp of the cached file.

Exceptions   
GassCacheException(gassCachec.globus_gass_cache_error_string( ret ) )
  list 
list ( self )

Return a list of all the entries in the cache.

Raises:

A GassCacheException is thrown if an error occurs while listing the cache.

Returns:

A list of entries is returned. Each entry is a 6-tuple. The first entry in the tuple is the url of the entry. The second is the local filename. The third is the timestamp. The fourth, a char with the state. The fifth, a string with the tag that holds the lock, if no lock is held, None. The sixth, is a list of pairs containing the tags assosciated with the entry. Each pair contains the tag name, and the number of tags with this name.

Exceptions   
GassCacheException(gassCachec.globus_gass_cache_error_string( ret ) )
  open 
open ( self,  cache_dir=None )

Open the given cache.

Opens the cache. If cache_dir is None, then use the value contained in the GLOBUS_GASS_CACHE_DEFAULT environment variable if it is defined, otherwise use ~/.gass_cache.

The cache_directory_path must be a directory. If it is a file, this call will fail with an exception.

If the specified directory does not exist, then this call will create the directory.

In order to insure thread safety, this function must be called in each of the thread which will use globus_gass_cache functions. For each call to globus_gass-cache_open(), the function globus_gass_cache_close() should be called when the code does not need to use globus_gass_cache functions anymore.

Implementation note: In the initial implementation, the cache_directory_path argument is ignored. Instead, the behavior is always that which results from cache_directory_path=NULL.

Arguments:

  • cache_dir Path to the cache directory to open. If None, the default is opened. Raises:

A GassCacheException is thrown if unable to initialize the module, or open the cache.

Exceptions   
ex

Table of Contents

This document was automatically generated on Tue Feb 4 16:47:03 2003 by HappyDoc version 2.1