[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

blob::cache(n) 1 doc "Blob. General content storage with deduplication"

Name

blob::cache - Blob - Write-through cache

Table Of Contents

Synopsis

Description

Welcome to the Blob project, written by Andreas Kupries.

For availability please read Blob - How To Get The Sources.

This package provides a blob store which caches blobs and uuid existence information in memory, to be used as a frontend for some other blob store.

Class API

::blob::cache create obj backend ?options...?

This constructor command creates a new instance obj of the class and returns the fully qualified name of that instance.

The backend is the instance command of the blob store the cache is sitting in front of. For information about the available options see section Options.

::blob::cache new backend ?options...?

This constructor command creates a new instance of the class and returns the fully qualified name of that instance.

The backend is the instance command of the blob store the cache is sitting in front of. For information about the available options see section Options.

Options

The cache constructor takes two options with which to configure the behaviour of the new instance. These are:

-blob-limit uint

Maximal size of the blob cache, as number of entries (not amount of memory). The default size is 100. Setting an empty string as the value makes the blob-cache part unlimited. Setting it to 0 disables the blob-cache part of the instance.

-uuid-limit uint

Maximal size of the uuid cache (existence information), as number of entries. The default size is 10000. Setting an empty string as the value makes the uuid-cache part unlimited. Setting it to 0 disables the uuid-cache part of the instance.

Standard API

As a derived class of blob instances of this class provide the following methods to their users:

<instance> put-string blob

This method adds the string blob to the instance and returns the blob's uuid as the result of the method. Adding the same string multiple times actually adds it only on the first call, and all invokations return the same uuid.

<instance> put-file path

This method adds the (binary) string found in the file at the specified path to the instance and returns the blob's uuid as the result of the method. Adding the same content multiple times actually adds it only on the first call, and all invokations return the same uuid.

<instance> put-channel chan

This method adds the (binary) string found in the channel chan to the instance and returns the blob's uuid as the result of the method. Adding the same content multiple times actually adds it only on the first call, and all invokations return the same uuid.

The content is read from chan once, starting at the current location. After the call the channel is positioned at EOF. Note that the caller has to close the channel.

<instance> new

This method returns a boolean value indicating if the last call to one of the put-* methods actually added a new blob (true), or not (false).

<instance> get-string uuid

This method locates the contents of blob uuid and returns them as the result of the method. An error is thrown if uuid is not known to the instance.

<instance> get-channel uuid

This method locates the contents of blob uuid and returns a channel containing it as the result of the method. An error is thrown if uuid is not known to the instance.

The returned channel is read-only, binary, and positioned at the beginning of the blob content. No assurances are made about the ability to seek the channel. It is the responsibility of the caller to close the channel after use.

<instance> get-file uuid

This method locates the contents of blob uuid and returns the path of a file containing it as the result of the method. An error is thrown if uuid is not known to the instance.

The returned file should be considered transient. It is owned by the caller and can be moved, modified, and deleted at will. It is the responsibility of the caller to delete the file after use.

<instance> store-to-file uuid path

This method locates the contents of blob uuid and stores them into the file with the specified path. Any previous content of the file is overwritten by this operation. The result of the method is the empty string. An error is thrown if uuid is not known to the instance.

<instance> remove uuid

This method locates the blob uuid and removes it from the instance. The result of the method is the empty string. An error is thrown if uuid is not known to the instance.

<instance> clear

This method removes all blobs from the instance. After the call the instance is empty. The result of the method is the empty string.

<instance> size

This method determines the number of blobs found in the instance and returns that number as the result of the method.

<instance> names ?pattern...?

This method determines the uuids of all blobs found in the store which match one or more of the specified glob patterns, and returns a list containing them.

<instance> exists uuid

This method returns a boolean value indicating if the blob uuid is known to the instance (true), or not (false).

<instance> push to ?uuids?
<instance> push-async donecmd to ?uuids?

This method copies the blobs specified by the list of uuids from the instance to the specified peer to. This has to be an object exporting the same API as documented for blob. The result of the method is the empty string.

If no set of uuids is specified the operation will push all blobs found in the instance, as if "uuids == * had been specified".

Note that the elements of uuids are interpreted as glob patterns.

In the push-async form the execution is done through the event-loop, invoking the command prefix donecmd when the operation completes, with no additional arguments.

<instance> pull from ?uuids?
<instance> pull-async donecmd from ?uuids?

This method copies the blobs specified by the list of uuids from the specified peer from to the instance. The peer has to be an object exporting the same API as documented for blob. The result of the method is the empty string.

If no set of uuids is specified the operation will pull all blobs found in the peer, as if "uuids == * had been specified".

Note that the elements of uuids are interpreted as glob patterns.

In the pull-async form the execution is done through the event-loop, invoking the command prefix donecmd when the operation completes, with no additional arguments.

<instance> sync with ?uuids?
<instance> sync-async donecmd with ?uuids?

This method exchanges the blobs specified by the list of uuids with the specified peer with, copying from and to the instance, as needed. The peer has to be an object exporting the same API as documented for blob. The result of the method is the empty string.

If no set of uuids is specified the operation will exchange all blobs found in the instance and the peer, as if "uuids == * had been specified".

Note that the elements of uuids are interpreted as glob patterns.

In the sync-async form the execution is done through the event-loop, invoking the command prefix donecmd when the operation completes, with no additional arguments.

Cache-specific API

<instance> cget option

This method returns the value of the named option. An error will be thrown if the option is not known. For information about the available options see section Options.

<instance> configure ?options...?

This method takes a series of options and values and reconfigures the instance accordingly. An error will be thrown if any of the specified options is not known. For information about the available options see section Options.

<instance> blobs

This methods returns the number of blobs currently loaded into the cache.

<instance> blobs-loaded

This method returns a list containing the uuids of the blobs currently loaded into the cache.

<instance> blobs-lru

This method returns a list containing the uuids of the blobs currently loaded into the cache, in order of last usage. In other words, the most recently used uuid is at the end of the list, and the least used uuid at the beginning.

<instance> uuids

This methods returns the number of uuid existence flags currently loaded into the cache.

<instance> uuids-loaded

This method returns a list containing the uuids for which existence flags are currently loaded into the cache.

<instance> uuids-lru

This method returns a list containing the uuids for which existence flags are currently loaded into the cache, in order of last usage. In other words, the most recently used uuid is at the end of the list, and the least used uuid at the beginning.

Bugs, Ideas, Feedback

Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Blob Tickets.

Please also report any ideas you may have for enhancements of either package(s) and/or documentation.

Keywords

blob, blob storage, content deduplication, content storage, deduplication, storage