libcvmfs_cache.h

Go to the documentation of this file.

#ifndef CVMFS_CACHE_PLUGIN_LIBCVMFS_CACHE_H_
#define CVMFS_CACHE_PLUGIN_LIBCVMFS_CACHE_H_

// Revision Changelog
// 1 --> 2:
//   - Add CVMCACHE_CAP_WRITE capability, adjust other capability constants
// 2 --> 3:
//   - Add cvmcache_get_session()
// 3 --> 4:
//   - Add breadcrumb management
// 4 --> 5:
//   - Add revision to breadcrumb
#define LIBCVMFS_CACHE_REVISION 5

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
// Map C++ classes to their C interface names
typedef class SimpleOptionsParser cvmcache_option_map;
#else
typedef struct OptionsManager cvmcache_option_map;
#endif

// Mirrors cvmfs::EnumHashAlgorithm protobuf definition
enum cvmcache_hash_algorithm {
  CVMCACHE_HASH_SHA1 = 1,
  CVMCACHE_HASH_RIPEMD160,
  CVMCACHE_HASH_SHAKE128
};

// Mirrors cvmfs::EnumStatus protobuf definition
enum cvmcache_status {
  CVMCACHE_STATUS_UNKNOWN = 0,
  CVMCACHE_STATUS_OK,
  CVMCACHE_STATUS_NOSUPPORT,  // Not implemented by the cache plugin
  CVMCACHE_STATUS_FORBIDDEN,  // Client is not allowed to perform the operation
  CVMCACHE_STATUS_NOSPACE,    // Cache is full
  CVMCACHE_STATUS_NOENTRY,    // Object is not in cache
  CVMCACHE_STATUS_MALFORMED,  // Malformed request
  CVMCACHE_STATUS_IOERR,      // General I/O error
  CVMCACHE_STATUS_CORRUPTED,  // Crc32 verification failed
  // Certain parts of a multipart request never arrived
  CVMCACHE_STATUS_TIMEOUT,
  CVMCACHE_STATUS_BADCOUNT,   // Attempt to set a negative reference count
  // Attempt to read from an offset larger than the object size
  CVMCACHE_STATUS_OUTOFBOUNDS,
  // Cache content could not be evicted to requested size
  CVMCACHE_STATUS_PARTIAL
};

// Mirrors cvmfs::EnumObjectType protobuf definition
enum cvmcache_object_type {
  CVMCACHE_OBJECT_REGULAR = 0,
  CVMCACHE_OBJECT_CATALOG,
  CVMCACHE_OBJECT_VOLATILE
};

// Mirrors cvmfs::EnumCapability protobuf definition
enum cvmcache_capabilities {
  CVMCACHE_CAP_NONE        = 0,
  // A read-only cache needs to be pre-populated by other means
  CVMCACHE_CAP_WRITE       = 1,
  // Proper refcounting is implemented; for lower tier caches, this capability
  // can be unset and reference counting can simply beomce file existence check
  CVMCACHE_CAP_REFCOUNT    = 2,
  CVMCACHE_CAP_SHRINK      = 4,   // clients can ask the cache to shrink
  CVMCACHE_CAP_INFO        = 8,   // cache plugin knows about its fill level
  CVMCACHE_CAP_SHRINK_RATE = 16,  // cache knows number of cleanup operations
  CVMCACHE_CAP_LIST        = 32,  // cache can return a list of objects
  CVMCACHE_CAP_ALL_V1      = 63,
  CVMCACHE_CAP_BREADCRUMB  = 64,  // cache can load and store breadcrumps
  CVMCACHE_CAP_ALL_V2      = 127,
};

#define CVMCACHE_SIZE_UNKNOWN (uint64_t(-1))

struct cvmcache_hash {
  unsigned char digest[20];
  char algorithm;
} __attribute__((__packed__));

struct cvmcache_object_info {
  struct cvmcache_hash id;
  uint64_t size;
  enum cvmcache_object_type type;
  int pinned;
  char *description;
};

struct cvmcache_info {
  uint64_t size_bytes;
  uint64_t used_bytes;
  uint64_t pinned_bytes;
  int64_t no_shrink;
};

struct cvmcache_context;

struct cvmcache_session {
  uint64_t id;
  char *repository_name;
  char *client_instance;
};

struct cvmcache_breadcrumb {
  struct cvmcache_hash catalog_hash;
  uint64_t timestamp;
  uint64_t revision;
};

int cvmcache_hash_cmp(struct cvmcache_hash *a, struct cvmcache_hash *b);
char *cvmcache_hash_print(const struct cvmcache_hash *h);

struct cvmcache_callbacks {
  int (*cvmcache_chrefcnt)(struct cvmcache_hash *id, int32_t change_by);
  int (*cvmcache_obj_info)(struct cvmcache_hash *id,
                           struct cvmcache_object_info *info);
  int (*cvmcache_pread)(struct cvmcache_hash *id,
                        uint64_t offset,
                        uint32_t *size,
                        unsigned char *buffer);
  int (*cvmcache_start_txn)(struct cvmcache_hash *id,
                            uint64_t txn_id,
                            struct cvmcache_object_info *info);
  int (*cvmcache_write_txn)(uint64_t txn_id,
                            unsigned char *buffer,
                            uint32_t size);
  int (*cvmcache_commit_txn)(uint64_t txn_id);
  int (*cvmcache_abort_txn)(uint64_t txn_id);

  int (*cvmcache_info)(struct cvmcache_info *info);
  int (*cvmcache_shrink)(uint64_t shrink_to, uint64_t *used);
  int (*cvmcache_listing_begin)(uint64_t lst_id,
                                enum cvmcache_object_type type);
  int (*cvmcache_listing_next)(int64_t lst_id,
                               struct cvmcache_object_info *item);
  int (*cvmcache_listing_end)(int64_t lst_id);

  int (*cvmcache_breadcrumb_store)(const char *fqrn,
                                   const cvmcache_breadcrumb *breadcrumb);
  int (*cvmcache_breadcrumb_load)(const char *fqrn,
                                  cvmcache_breadcrumb *breadcrumb);

  int capabilities;
};

void cvmcache_init_global();
void cvmcache_cleanup_global();
int cvmcache_is_supervised();

struct cvmcache_context *cvmcache_init(struct cvmcache_callbacks *callbacks);
int cvmcache_listen(struct cvmcache_context *ctx, char *locator);
void cvmcache_process_requests(struct cvmcache_context *ctx, unsigned nworkers);
void cvmcache_ask_detach(struct cvmcache_context *ctx);
void cvmcache_terminate(struct cvmcache_context *ctx);
void cvmcache_wait_for(struct cvmcache_context *ctx);
uint32_t cvmcache_max_object_size(struct cvmcache_context *ctx);

void cvmcache_spawn_watchdog(const char *crash_dump_file);
void cvmcache_terminate_watchdog();

void cvmcache_get_session(cvmcache_session *session);


// Options parsing from libcvmfs without "libcvmfs legacy" support

cvmcache_option_map *cvmcache_options_init();
void cvmcache_options_fini(cvmcache_option_map *opts);
void cvmcache_options_set(cvmcache_option_map *opts,
                          const char *key, const char *value);
int cvmcache_options_parse(cvmcache_option_map *opts, const char *path);
void cvmcache_options_unset(cvmcache_option_map *opts, const char *key);
char *cvmcache_options_get(cvmcache_option_map *opts, const char *key);
char *cvmcache_options_dump(cvmcache_option_map *opts);
void cvmcache_options_free(char *value);

#ifdef __cplusplus
}
#endif

#endif  // CVMFS_CACHE_PLUGIN_LIBCVMFS_CACHE_H_