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__
|
__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.
|
|
__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.
|
|
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:
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:
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.
|
|
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:
A GassCacheException is thrown if unable to initialize the module, or open
the cache.
|
|