Home -> Toolkit -> Docs -> 2.4 -> Gass -> Cache

GASS: Cache Management Function Reference

• Overview
• GASS Cache Activation and Deactivation
• Functions
• Error Codes

GASS Cache Management Overview

The GASS cache management API defines calls for manipulating a local file cache.

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)

GASS Cache Activation and Deactivation

 GASS uses standard Globus module activation and deactivation. Before any GASS cache functions are called, the following function must be called:

globus_module_activate(GLOBUS_GASS_CACHE_MODULE);

This function returns GLOBUS_SUCCESS if GASS was successfully initialized, and you are therefore allowed to subsequently call GASS cache functions. Otherwise, and error code is returned, and GASS functions should not be subsequently called. This function may be called multiple times.

To deactivate GASS cache, the following function must be called:

globus_module_deactivate(GLOBUS_GASS_CACHE_MODULE);

This function should be called once for each time the GASS cache was activated.

GASS Cache Management Functions

 

int
globus_gass_cache_open(
    char *cache_directory_path,
    globus_gass_cache_t *cache_handle)

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.

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.

Parameters:

• Input:
  • cache_directory_path: Path to the cache directory to open. Can be NULL (see above)
• Output:
  • cache_handle: Structure containing all the necessary information to access the cache (file names, descriptor,...) Some files are also opened: globus_gass_cache_close() must be called subsequently to close those files.
• Returns:
  • GLOBUS_SUCCESS or error code:
  • GLOBUS_GASS_CACHE_ERROR_CACHE_ALREADY_OPENED
  • GLOBUS_GASS_CACHE_ERROR_NAME_TOO_LONG if the cache directory path is too long
  • GLOBUS_GASS_CACHE_ERROR_NO_HOME if cache_directory_path is NULL and the env. variable
  • GLOBUS_GASS_CACHE_DEFAULT is empty and the env. variable $HOME is not defined !
  • GLOBUS_GASS_CACHE_ERROR_CAN_NOT_CREATE if the cache directory or any necessary file can not be created.

---

int
globus_gass_cache_close(
    globus_gass_cache_t *cache_handle)

Close (NOT delete) a previously opened cache.

Parameters:

• Input:
  • cache_handle: Handler to the opened cache directory to use.
• Output:
  • cache_handle: set to "not initialized".
• Returns:
  • GLOBUS_SUCCESS or error code:
  • GLOBUS_GASS_CACHE_ERROR_CACHE_NOT_OPENED

---

int
globus_gass_cache_add(
    globus_gass_cache_t *cache_handle,
    char *url,
    char *tag,
    globus_bool_t create,
    unsigned long *timestamp,
    char **local_filename)

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

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:

• Input:
  • cache_handle: handler to the 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 using the cache.  This is usually the GRAM_JOB_CONTACT. It can be NULL of empty; the tag "null" is then used.
  • create: tells if the cache should be created, if it does not already exist.
• Output:
  • timestamp: time stamp of the cached file, set by globus_gass_cache_add_done(), or globus_gass_cache_delete().
  • local_filename: path 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)
• Return:
  • GLOBUS_GASS_CACHE_URL_NOT_FOUND
  • GLOBUS_GASS_CACHE_ADD_NEW
  • GLOBUS_GASS_CACHE_ADD_EXISTS
  • Any GASS Cache Error Code

 

---

int
globus_gass_cache_add_done(
    globus_gass_cache_t *cache_handle,
    char *url,
    char *tag,
    unsigned long timestamp)

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

Parameters:

• Input:
  • cache_handle: handler to the 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.
  • timestamp: time stamp of the cached file, set by globus_gass_cache_add_done(), or globus_gass_cache_delete()
• Output:
  • none (the state file us updated, and the cache file lock is removed)
• Return:
  • GLOBUS_SUCCESS
  • Any GASS Cache Error Code

---

int
globus_gass_cache_delete_start(
    globus_gass_cache_t *cache_handle,
    char *url,
    char *tag,
    unsigned long *timestamp)

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

Parameters:

• Input:
  • cache_handle: handler to the 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.
• Output:
  • timestamp: time stamp of the cached file, set by globus_gass_cache_add_done(), or globus_gass_cache_delete()
• Return:
  • GLOBUS_SUCCESS
  • Any GASS Cache Error Code

---

int
globus_gass_cache_delete(
    globus_gass_cache_t *cache_handle,
    char *url,
    char *tag,
    unsigned long timestamp,
    globus_bool_t is_locked)

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:

• Input:
  • cache_handle: handler to the 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.  This is usually the GRAM_JOB_CONTACT. It can be NULL of empty; the tag "null" is then used.
  • timestamp: time stamp of the cached file
  • is_locked: indicates if this cached entry was locked during a previous call to globus_gass_cache_add() or globus_gass_cache_delete_start()
• Output:
  • none
• Return:
  • GLOBUS_SUCCESS
  • Any GASS Cache Error Code

---

int
globus_gass_cache_cleanup_tag(
    globus_gass_cache_t *cache_handle,
    char *url,
    char *tag)

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:

• Input:
  • cache_handle: handler to the 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.  This is usually the GRAM_JOB_CONTACT. It can be NULL of empty; the tag "null" is then used.
• Output:
  • none
• Return:
  • GLOBUS_SUCCESS
  • Any GASS Cache Error Code

---

int
globus_gass_cache_cleanup_file(
    globus_gass_cache_t *cache_handle,
    char *url)

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.

Parameters:

• Input:
  • cache_handle: handler to the opened cache directory to use.
  • url: url of the cached file to set as "done" (unlock).

• Output:
  • none
• Return:
  • GLOBUS_SUCCESS
  • Any GASS Cache Error Code

---

typedef struct
{
char * tag; /* tag name */
int count; /* number of tags with this name */
} globus_gass_cache_tag_t;


typedef struct
{
char * url; /* url */
char * filename; /* local filename */
unsigned long timestamp; /* timestamp */
                            /* (seconds since the epoch) */
char * lock_tag; /* the tag that has acquired this */
                    /* entry's lock, or GLOBUS_NULL if */
                     /* the entry is unlocked */
unsigned long num_tags; /* number of tags in the tag array */
globus_gass_cache_tag_t * tags; /* array of tags */
} globus_gass_cache_entry_t;


int
globus_gass_cache_list(
    globus_gass_cache_t *cache_handle,
    globus_gass_cache_entry_t **entries,
    int *size)


Return the entries of the cache in *entries as an array of globus_gass_cache_entry_t structures, and return the number of elements in this array in *size.

 

Parameters:

• Input:
  • cache_handle: handler to the opened cache directory, to use.
• Output:
  • entries: array of globus_gass_cache_entry_t structure describing each cache entry
  • size: size of the "entries" array (num of entries)
• Return:
  • GLOBUS_SUCCESS
  • Any GASS Cache Error Code

---

int
globus_gass_cache_list_free(
    globus_gass_cache_entry_t *entries,
    int size)

Free the array of cache entries previously returned by globus_gass_cache_list().

Parameters:

• Input:
  • entries: array of globus_gass_cache_entry_t structure describing each cache entry
  • size: size of the "entries" array (num of entries)

• Return:
  • GLOBUS_SUCCESS

---

int
globus_gass_cache_error_string(
    int errorcode)

Returns a pointer to an error description string.

Parameters:

• Input:
  • errorcode: error code returned by a previously-called globus_gass_cache function
• Output:
  • none
• Returns:
  • Pointer to an error message, or NULL if invalid error code

GASS Cache Management Errors Codes