Provided by: libglobus-gass-cache-doc_10.3-3_all bug

NAME

       globus_gass_cache - Globus GASS Cache

        - Globus GASS Cache.

SYNOPSIS

   Macros
       #define GLOBUS_GASS_CACHE_MODULE   (&globus_i_gass_cache_module)
           module_descriptor

   Typedefs
       typedef struct globus_i_gass_cache_t * globus_gass_cache_t
           GASS Cache Handle.

   Functions
       int globus_gass_cache_open (const char *cache_directory_path, globus_gass_cache_t
           *cache_handlep)
           Open a GASS Cache.
       int globus_gass_cache_close (globus_gass_cache_t *cache_handlep)
           Close a cache handle.
       int globus_gass_cache_add (globus_gass_cache_t cache_handle, const char *url, const char
           *tag, globus_bool_t create, unsigned long *timestamp, char **local_filename)
           Add a tag to an URL in the cache.
       int globus_gass_cache_add_done (globus_gass_cache_t cache_handle, const char *url, const
           char *tag, unsigned long timestamp)
           Complete adding a cache entry and unlock it.
       int globus_gass_cache_query (globus_gass_cache_t cache_handle, const char *url, const char
           *tag, globus_bool_t wait_for_lock, unsigned long *timestamp, char **local_filename,
           globus_bool_t *is_locked)
           Query the GASS Cache.
       int globus_gass_cache_delete_start (globus_gass_cache_t cache_handle, const char *url,
           const char *tag, unsigned long *timestamp)
           Remove a cache tag.
       int globus_gass_cache_delete (globus_gass_cache_t cache_handle, const char *url, const
           char *tag, unsigned long timestamp, globus_bool_t is_locked)
           Remove one instance of the tag from the cache entry's tag list.
       int globus_gass_cache_cleanup_tag (globus_gass_cache_t cache_handle, const char *url,
           const char *tag)
           Remove a tag from a cache entry.
       int globus_gass_cache_cleanup_tag_all (globus_gass_cache_t cache_handle, char *tag)
           Remove a tag from all cache entries

       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. "
   int globus_gass_cache_mangle_url (const globus_gass_cache_t cache_handle, const char *url,
       char **mangled_url, int *length)
       Convert a URL to a string suitable as a file path.
   int globus_gass_cache_mangle_tag (const globus_gass_cache_t cache_handle, const char *tag,
       char **mangled_tag, int *length)
       Convert a tag to a string suitable as a file path.
   int globus_gass_cache_get_cache_dir (const globus_gass_cache_t cache_handle, char **cache_dir)
       Get the GASS Cache's root directory.
   int globus_gass_cache_get_dirs (const globus_gass_cache_t cache_handle, const char *url, const
       char *tag, char **global_root, char **local_root, char **tmp_root, char **log_root, char
       **global_dir, char **local_dir)
       Get the set of directories used by a GASS Cache.
   int globus_gass_cache_get_cache_type_string (const globus_gass_cache_t cache_handle, char
       **cache_type)
       Get the type of GASS Cache directory layout.
   const char * globus_gass_cache_error_string (int error_code)
       Look up the error string corresponding to a GASS Cache error.

Detailed Description

       Globus GASS Cache.

       The GASS cache management API is part of the Globus module called 'GASS', (Global Access
       to Secondary Storage) 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 associated with the cache entry.

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

       The following functions are part of the API:

       • globus_gass_cache_open()globus_gass_cache_close()globus_gass_cache_add()globus_gass_cache_add_done()globus_gass_cache_delete_start()globus_gass_cache_delete()globus_gass_cache_cleanup_tag()globus_gass_cache_cleanup_tag_all()globus_gass_cache_mangle_url()globus_gass_cache_mangle_tag()globus_gass_cache_get_dirs()globus_gass_cache_get_cache_dir()

Typedef Documentation

   typedef struct globus_i_gass_cache_t* globus_gass_cache_t
       GASS Cache Handle. Data structure used to store information concerning an open cache
       directory. This structure MUST NOT be modified directly, but passed to the
       globus_gass_cache functions

Function Documentation

   int globus_gass_cache_add (globus_gass_cache_t cache_handle, const char * url, const char *
       tag, globus_bool_t create, unsigned long * timestamp, char ** local_filename) [extern]
       Add a tag to an URL in the cache. Create a new cache file or add a tag on it.

       If the URL is already in the cache but is locked, 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_CACHE_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.

       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.

       Note
           the local_filename MUST be free by the user in a subsequent operation, using free()

       Parameters
           cache_handle Handle 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/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.
           create Flag to create if it does not already exist.
           timestamp Timestamp of the cached file, set by globus_gass_cache_done(), (or
           globus_gass_cache_delete() ).
           local_filename Path the the local file caching the file specified by 'url'. NULL if
           'url' not yet cached and creation not requested (create false).

       Returns

           • GLOBUS_GASS_CACHE_URL_NOT_FOUND

           • GLOBUS_GASS_CACHE_ADD_NEW

           • GLOBUS_GASS_CACHE_ADD_EXISTS

           • or any of the defined gass error code.

   int globus_gass_cache_add_done (globus_gass_cache_t cache_handle, const char * url, const char
       * tag, unsigned long timestamp) [extern]
       Complete adding a cache entry and unlock it. 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 Handle 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 Timestamp of the cached file.

       Returns
           globus_gass_cache_add_done() returns GLOBUS_SUCCESS or any of the defined GASS Cache
           error codes.

   int globus_gass_cache_cleanup_tag (globus_gass_cache_t cache_handle, const char * url, const
       char * tag) [extern]
       Remove a tag from a cache entry. 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.

       This function does not block on a locked reference.

       Note
           The GLOBUS_GRAM job manager will automatically call this function with a tag of
           getenv('GLOBUS_GRAM_JOB_CONTACT') upon completion of a job.

       Parameters
           cache_handle Handle 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/are using the cache. This is usually the
           GLOBUS_GRAM_JOB_CONTACT. Can be NULL or empty; the tag 'null' is then used.

       Returns
           The globus_gass_cache_cleanup_tag() function returns GLOBUS_SUCCESS or any of the
           defined GASS Cache error codes.

   int globus_gass_cache_cleanup_tag_all (globus_gass_cache_t cache_handle, char * tag) [extern]
       Remove a tag from all cache entries

       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. This function does not block on a locked reference. This function differs from
       globus_gass_cache_cleanup_tag() in that this cleans up all URLs related with this tag.

       Note
           The GLOBUS_GRAM job manager will automatically call this function with a tag of
           getenv('GLOBUS_GRAM_JOB_CONTACT') upon completion of a job.

       Parameters
           cache_handle Handle to the opened cache directory to use.
           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.

       Returns
           The globus_gass_cache_cleanup_tag_all() function returns GLOBUS_SUCCESS or any of the
           defined GASS Cache error codes.

   int globus_gass_cache_close (globus_gass_cache_t * cache_handlep)
       Close a cache handle. Close (NOT delete) a previously opened cache:

       • close the opened files and

       • free the memory allocated for the cache_handle.

       • mark the handle as 'not initialized'.

       Parameters: cache_handle: Handle to the opened cache directory to use.

       cache_handle->is_init set to 'not initialized' and all the files opened bu
       globus_gass_cache_open are closed .

       Returns: GLOBUS_SUCCESS or error code: GLOBUS_GASS_CACHE_ERROR_CACHE_NOT_OPENED

   int globus_gass_cache_delete (globus_gass_cache_t cache_handle, const char * url, const char *
       tag, unsigned long timestamp, globus_bool_t is_locked) [extern]
       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.

       This call will leave the cache entry unlocked.

       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(). The cache file should be
       locked by the corresponding url/tag, or an error is returned. If it is locked by the
       corresponding url/tag, then the normal operation occur, without blocking (remove one
       instance from the tag update the timestamp and unlock the cache).

       If is_locked==GLOBUS_FALSE, eventually wait the cache is not locked any more, and then
       proceed with the normal operations.(remove one instance from the tag list and update the
       timestamp).

       Parameters
           cache_handle Handle 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/are using the cache. This is usually the
           GLOBUS_GRAM_JOB_CONTACT. Can be NULL or empty; the tag 'null' is then used.
           timestamp Timestamp of the cached file.
           is_locked Indicate if this cache entry was locked during a previous call to
           globus_gass_cache_add() or globus_gass_cache_delete_start().

       Returns
           The globus_gass_cache_delete() function returns GLOBUS_SUCCESS or any of the defined
           GASS Cache error codes.

   int globus_gass_cache_delete_start (globus_gass_cache_t cache_handle, const char * url, const
       char * tag, unsigned long * timestamp) [extern]
       Remove a cache tag. Lock the cache entry for the URL, and return the cache entry's current
       timestamp in *timestamp. This function will block if the data file is already locked,
       until it is unlocked.

       Parameters
           cache_handle Handle 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 Timestamp of the cached file, set by globus_gass_cache_done(), (or
           globus_gass_cache_delete() ).

       Returns
           The globus_gass_cache_delete_start() function returns GLOBUS_SUCCESS or any of the
           defined GASS Cache error code.

   const char * globus_gass_cache_error_string (int error_code) [extern]
       Look up the error string corresponding to a GASS Cache error. Return a pointer on an error
       description string.

       Parameters
           error_code error code returned by a previously called globus_gass_cache function.

       Returns
           The globus_gass_cache_error_string() function returns a pointer to an error message,
           or NULL if error_code is invalid.

   int globus_gass_cache_get_cache_dir (const globus_gass_cache_t cache_handle, char **
       cache_dir) [extern]
       Get the GASS Cache's root directory. Get a the root cache of directory. This is exported
       for use in the globus_gass_cache program.

       Parameters
           cache_handle Handle to the opened cache directory to use.
           cache_dir Pointer to the cache directory

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GASS_CACHE_ERROR_NO_MEMORY No memory

   int globus_gass_cache_get_cache_type_string (const globus_gass_cache_t cache_handle, char **
       cache_type) [extern]
       Get the type of GASS Cache directory layout. Get a string which describes the cache type
       ('normal' or 'flat')

       Parameters
           cache_handle Handle to the opened cache directory to use.
           cache_type Pointer to the strdup()ed string

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GASS_CACHE_ERROR_NO_MEMORY No memory

   int globus_gass_cache_get_dirs (const globus_gass_cache_t cache_handle, const char * url,
       const char * tag, char ** global_root, char ** local_root, char ** tmp_root, char **
       log_root, char ** global_dir, char ** local_dir) [extern]
       Get the set of directories used by a GASS Cache. Gets a bunch of directories. This is
       exported for use in the globus_gass_cache program.

       Parameters
           cache_handle Handle to the opened cache directory to use.
           url The incoming URL
           tag The incoming tag
           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

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GASS_CACHE_ERROR_NO_MEMORY No memory

   int globus_gass_cache_mangle_tag (const globus_gass_cache_t cache_handle, const char * tag,
       char ** mangled_tag, int * length) [extern]
       Convert a tag to a string suitable as a file path. Mangles the given tag into a chunk
       suitable for using as a file / path name. This is exported for use in the
       globus_gass_cache program.

       Parameters
           cache_handle Handle to the opened cache directory to use.
           tag The incoming tag to mangle (NULL-terminated)
           mangled_tag Pointer to the output string; a buffer for the real string is malloc()ed
           for the application. If mangled is NULL, then no such buffer is allocated, and no
           mangled string is created. This can be useful to just get the length of the mangled
           string.
           length A pointer to the length of the resulting string. If NULL, this is not assigned
           to.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GASS_CACHE_ERROR_NO_MEMORY No memory

   int globus_gass_cache_mangle_url (const globus_gass_cache_t cache_handle, const char * url,
       char ** mangled_url, int * length) [extern]
       Convert a URL to a string suitable as a file path. Mangles the given URL into a chunk
       suitable for using as a file / path name. This is exported for use in the
       globus_gass_cache program.

       Parameters
           cache_handle Handle to the opened cache directory to use.
           url The incoming URL to mangle (NULL-terminated)
           mangled_url Pointer to the output string; a buffer for the real string is malloc()ed
           for the application. If mangled is NULL, then no such buffer is allocated, and no
           mangled string is created. This can be useful to just get the length of the mangled
           string.
           length A pointer to the length of the resulting string. If NULL, this is not assigned
           to.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GASS_CACHE_ERROR_NO_MEMORY No memory

   int globus_gass_cache_open (const char * cache_directory_path, globus_gass_cache_t *
       cache_handlep)
       Open a GASS Cache. 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
       ~/.globus_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 (see above)
           cache_handlep Structure containning all the necessary information to access the cache
           (file names, descriptor,...) (see globus_gass_gache.h) Some files are also opened:
           globus_gass_cache_close() must be called subsequently to close those files. This
           parameter is modified by the globus_gass_cache_open()

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GASS_CACHE_ERROR_CACHE_ALREADY_OPENED Handle already opened
           GLOBUS_GASS_CACHE_ERROR_NAME_TOO_LONG Path name too long
           GLOBUS_GASS_CACHE_ERROR_NO_HOME Can't find home directory for default cache path

   int globus_gass_cache_query (globus_gass_cache_t cache_handle, const char * url, const char *
       tag, globus_bool_t wait_for_lock, unsigned long * timestamp, char ** local_filename,
       globus_bool_t * is_locked) [extern]
       Query the GASS Cache. Query if an item is in the cache

       This call will block only if wait_for_lock is GLOBUS_TRUE

       Parameters
           cache_handle Handle to the opened cache directory to use.
           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 Timestamp of the cached file, set by globus_gass_cache_done(), (or
           globus_gass_cache_delete() ).
           local_filename Path the the local file caching the file specified by 'url'. NULL if
           'url' not yet cached and creation not requested (create false).
           is_locked GLOBUS_TRUE if the file is currently (at return time) locked.

       Returns
           The globus_gass_cache_query() function returns GLOBUS_SUCCESS,
           GLOBUS_GASS_CACHE_URL_NOT_FOUND, or any of the defined gass error code.

Author

       Generated automatically by Doxygen for globus_gass_cache from the source code.