Package pyGlobus :: Module gassCache :: Class GassCache
[show private | hide private]
[frames | no frames]

Class GassCache


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)
Method Summary
  __init__(self)
Constructs an instance.
  __del__(self)
Destroy an instance.
  add(self, url, tag, create)
Add a URL to the cache.
  add_done(self, url, tag, timestamp)
Set the timestamp in the cache entry for the URL, and then unlock the cache entry.
  cache_get_dirs(self, url, tag)
Gets a bunch of directories.
  cache_query(self, url, tag, wait_for_lock, timestamp, filename)
Query if an item is in the cache This call will block only if wait_for_lock is GLOBUS_TRUE
  cleanup_tag(self, url, tag)
Remove the given tag from the cache table.
  close(self)
Close the given cache.
  delete(self, url, tag, timestamp, isLocked)
Delete a tag entry from the cache.
  delete_start(self, url, tag)
Lock the cache entry prior to deleting it.
  mangle_tag(self, tag)
Mangles the given tag into a chunk suitable for using as a file / path name.
  mangle_url(self, url)
Mangles the given URL into a chunk suitable for using as a file / path name.
  open(self, cache_dir)
Open the given cache.

Method Details

__init__(self)
(Constructor)

Constructs an instance.

Activates the underlying globus gass cache module.
Raises:
GassCacheException - A GassCacheException is thrown if unable to initialize the module, or open the cache.

__del__(self)
(Destructor)

Destroy an instance.

Deactivates the underlying module. Before deleting the module, close should be called once for each open call.
Raises:
GassCacheException - A GassCacheException is thrown if unable to deactivate the module.

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.
Parameters:
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.
Returns:
  • *ret* a return code specifying GLOBUS_SUCCESS,
GLOBUS_GASS_CACHE_ADD_NEW,GLOBUS_GASS_CACHE_URL_NOT_FOUND, or GLOBUS_GASS_CACHE_ADD_EXISTS
  • *fileString* a string specifying the path to the cached file
  • *timestamp* an integer that is the timestamp of the cached file set by add_done or delete
Raises:
GassCacheException - A GassCacheException is thrown if an error occurs while adding the url to the cache.

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.
Parameters:
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
Returns:
None
Raises:
GassCacheException - A GassCacheException is thrown if an error occurs while unlocking the cache entry.

cache_get_dirs(self, url, tag)

Gets a bunch of directories. This is exported for use in the globus_gass_cache program.
Parameters:
url - The incoming url
tag - The incoming tag
Returns:
A six-tuple containing: local_root - Pointer to the "local root" directory global_root - Pointer to the "global root" directory tmp_root - Pointer to the "tmp root" directory log_root - Pointer to the root log directory local_dir - Pointer to the related "local" directory global_dir - Pointer to the related "global" directory

cache_query(self, url, tag, wait_for_lock, timestamp, filename)

Query if an item is in the cache This call will block only if wait_for_lock is GLOBUS_TRUE
Parameters:
url - url of the file to query. It is used as the main key to the cache entries.
tag - tag specifying which job is/are using the cache. This is usually the GLOBUS_GRAM_JOB_CONTACT. Can be NULL or empty; the tag "null" is then used.
wait_for_lock - If GLOBUS_TRUE, wait for any lock existing lock to be released. If GLOBUS_FALSE, doesn't wait for a lock to be released.
timestamp - time stamp of the cached file, set by globus_gass_cache_done(), (or globus_gass_cache_delete() ).
Returns:
True if is locked, false otherwise.

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.
Parameters:
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:
GassCacheException - A GassCacheException is thrown if an error occurs while cleaning up the tag entry.

close(self)

Close the given cache.
Raises:
GassCacheException - A GassCacheException is thrown if unable to close the cache.

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.
Parameters:
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()
Returns:
None
Raises:
GassCacheException - A GassCacheException is thrown if an error occurs while deleting the cache entry.

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.
Parameters:
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.
Returns:
Returns the timestamp of the cached file.
Raises:
GassCacheException - A GassCacheException is thrown if an error occurs while locking the cache entry.

mangle_tag(self, tag)

Mangles the given tag into a chunk suitable for using as a file / path name.
Parameters:
tag - The incoming tag to mangle
Returns:
The mangled tag.

mangle_url(self, url)

Mangles the given URL into a chunk suitable for using as a file / path name.
Parameters:
url - The incoming URL to mangle
Returns:
The mangled URL.

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_dir 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.

Note: It is recommended that proglobus_grams started via GLOBUS_GRAM pass a tag value of getenv("GLOBUS_GRAM_JOB_CONTACT"), since upon completion of a job GLOBUS_GRAM will automatically cleanup entries with this tag.
Parameters:
cache_dir - Path to the cache directory to open. If None, the default is opened.
Returns:
None
Raises:
GassCacheException - A GassCacheException is thrown if unable to initialize the module, or open the cache.

Generated by Epydoc 2.1 on Tue Apr 4 14:32:52 2006 http://epydoc.sf.net