NAME
globus_gass_cache_add
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_add
cache_handle
url
tag
create
DESCRIPTION
This command is used to create a new cache file or add a tag on it.
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 in local_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==GLOBUS_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==GLOBUS_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==NULL, 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.
The returned local_filename should be subsequently freed by calling globus_free(local_filename).
PARAMETERS
cache_handle - Handler to be opened cache directory to use.
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/are using the cache. This is usually the GLOBUS_GRAM_JOB_CONTACT. Can be NULL or empty; the tag "null" is then used.
create - Tells if the cache entry should be created if it is not already existing.
RETURN VALUE
On success globus_gass_cache_add returns 0, timestamp and local filename. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_add $cache_handle $sourcefile $GLOBUS_NULL $GLOBUS_TRUE ] result timestamp local_filename
BUGS
None
TODO
None
SEE ALSO
NAME
globus_gass_cache_add_done
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_add_done
cache_handle
url
tag
timestamp
DESCRIPTION
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
cache_handle - Handler to be opened cache directory to use.
url - URL of the cached file to set as "done" (unlock).
tag - Tag specifying which job has locked the cache and must therfor 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.
RETURN VALUE
On success globus_gass_cache_add_done returns 0. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_add_done $cache_handle $sourcefile $GLOBUS_NULL timestamp ] result
BUGS
None
TODO
None
SEE ALSO
NAME
globus_gass_cache_cleanup_tag
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_cleanup_tag
cache_handle
url
tag
DESCRIPTION
This command is used to 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.
PARAMETERS
cache_handle - Handler to be opened cache directory to use.
url - URL of the cached file to set as "done" (unlock).
tag - Tag specifying which job is using the cache. It can be NULL of empty; the tag "null" is then used.
RETURN VALUE
On success globus_gass_cache_cleanup_tag returns 0. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_cleanup_tag $cache_handle $sourcefile $GLOBUS_NULL ] result
BUGS
None
TODO
None
SEE ALSO
NAME
globus_gass_cache_cleanup_tag_all
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_cleanup_tag_all
cache_handle
tag
DESCRIPTION
This command is used to 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.
PARAMETERS
cache_handle - Handler to be opened cache directory to use.
tag - Tag specifying which job is using the cache. It can be NULL of empty; the tag "null" is then used.
RETURN VALUE
On success globus_gass_cache_cleanup_tag_all returns 0. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_cleanup_tag_all $cache_handle $GLOBUS_NULL ] result
BUGS
None
TODO
None
SEE ALSO
NAME
globus_gass_cache_close
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_close
cache_handle
DESCRIPTION
This command is used to close (NOT delete) a previously opened cache.
PARAMETERS
cache_handle - The handle to be closed.
RETURN VALUE
On success globus_gass_cache_close returns 0. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_close $cache_handle ] result
BUGS
None
TODO
None
SEE ALSO
NAME
globus_gass_cache_delete
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_delete
cache_handle
url
tag
timestamp
is_locked
DESCRIPTION
This command is used to 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 globus_gass_cache_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
cache_handle - Handler to be opened cache directory to use.
url - URL of the cached file to set as "done" (unlock).
tag - Tag specifying which job is using the cache. It can be NULL of empty; the tag "null" is then used.
RETURN VALUE
On success globus_gass_cache_delete returns 0. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_delete $cache_handle $sourcefile $GLOBUS_NULL $timestamp $GLOBUS_TRUE ] result
BUGS
None
TODO
None
SEE ALSO
NAME
globus_gass_cache_delete_start
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_delete_start
cache_handle
url
tag
DESCRIPTION
This command is used to lock the cache entry for the URL, and return the cache entry's current timestamp in timestamp.
PARAMETERS
cache_handle - Handler to be opened cache directory to use.
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.
RETURN VALUE
On success globus_gass_cache_delete_start returns 0 and timestamp. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_delete_start $cache_handle $sourcefile $GLOBUS_NULL ] result timestamp
BUGS
None
TODO
None
SEE ALSO
NAME
globus_gass_cache_get_cache_dir
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_get_cache_dir
cache_handle
DESCRIPTION
This command is used to get a the root cache of directory.
This is exported for use in the globus_gass_cache program.
PARAMETERS
cache_handle - Handler to be opened cache directory to use.
RETURN VALUE
On success globus_gass_cache_get_cache_dir returns 0 and cache_dir. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_get_cache_dir $cache_handle ] result cache_dir
BUGS
None
TODO
None
NAME
globus_gass_cache_get_cache_type_string
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_get_cache_type_string
cache_handle
DESCRIPTION
This command is used to get a string which describes the cache type ("normal" or "flat").
PARAMETERS
cache_handle - Handler to be opened cache directory to use.
RETURN VALUE
On success globus_gass_cache_get_cache_type_string returns 0 and cache_type. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_get_cache_type_string $cache_handle ] result cache_type
BUGS
None
TODO
None
NAME
globus_gass_cache_get_dirs
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_get_dirs
cache_handle
url
tag
DESCRIPTION
This command is used to get a bunch of directories.
This is exported for use in the globus_gass_cache program.
PARAMETERS
cache_handle - Handler to be opened cache directory to use.
url - The incoming URL.
tag - The incoming tag.
RETURN VALUE
On success globus_gass_cache_get_dirs returns 0, local_root, global_root, tmp_root, log_root, local_dir and global_dir. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_get_dirs $cache_handle $sourcefile $GLOBUS_NULL ] result global_root local_root tmp_root log_root global_dir local_dir
BUGS
None
TODO
None
NAME
globus_gass_cache_mangle_tag
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_mangle_tag
cache_handle
tag
DESCRIPTION
This command is used to mangle the given tag into a chunk suitable for using as a file/path name.
PARAMETERS
cache_handle - Handler to be opened cache directory to use.
tag - The incoming tag to mangle (\0 terminated).
RETURN VALUE
On success globus_gass_cache_mangle_tag returns 0, mangled_tag and length. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_mangle_tag $cache_handle $GLOBUS_NULL ] result mangled_tag length
BUGS
None
TODO
None
SEE ALSO
NAME
globus_gass_cache_mangle_url
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_mangle_url
cache_handle
url
DESCRIPTION
This command is used to mangle the given URL into a chunk suitable for using as a file/path name.
PARAMETERS
cache_handle - Handler to be opened cache directory to use.
url - The incoming URL to mangle (\0 terminated).
RETURN VALUE
On success globus_gass_cache_mangle_url returns 0, mangled_url and length. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_mangle_url $cache_handle $sourcefile ] result mangled_url length
BUGS
None
TODO
None
SEE ALSO
NAME
globus_gass_cache_open
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_open
cache_directory_path
DESCRIPTION
This command is used to open the cache specified by the cache_directory_path argument, and return a cache handle that can be used in subsequent cache calls.
If cache_directory_path is NULL, 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 a non-0 return value.
If the specified directory does not exist, then this call will create the directory.
PARAMETERS
cache_directory_path - Path to the cache directory to open. Can be NULL.
RETURN VALUE
On success globus_gass_cache_open returns 0 and cache_handle. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_open "/tmp/test_gass_cache" ] result cache_handle
BUGS
None
TODO
None
SEE ALSO
NAME
globus_gass_cache_query
SYNOPSIS
package require globus_gass_cache
globus_gass_cache_query
cache_handle
url
tag
wait_for_lock
DESCRIPTION
This command is used to query if an item is in the cache.
This call will block only if wait_for_lock is GLOBUS_TRUE.
PARAMETERS
cache_handle - Handler to be opened cache directory to use.
url - URL of the cached file to query. It is used as the main key to the cache entries.
tag - Tag specifying which job has locked the cache and must therfor be unlocked.It is an error to call this function with a tag which does not currently own the cache lock.
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.
RETURN VALUE
On success globus_gass_cache_query returns 0, timestamp, local_filename and is_locked. On error, this command will raise an error and must be caught using the appropriate catch command.
EXAMPLE
lassign [ globus_gass_cache_query $cache_handle $sourcefile $GLOBUS_NULL $GLOBUS_TRUE ] result timestamp local_filename is_locked
BUGS
None
TODO
None