puppetlabs.stockpile.queue
createclj
(create directory)Creates a new queue in directory, which must not exist, and returns the queue. If an exception is thrown, the directory named may or may not exist and may or may not be empty.
Creates a new queue in directory, which must not exist, and returns the queue. If an exception is thrown, the directory named may or may not exist and may or may not be empty.
discardclj
(discard q entry)(discard q entry destination)Atomically and durably discards the entry (returned by store) from the queue. The discarded data will be placed at the destination path (durably if possible), when one is provided. This should be much more efficient, and likely safer if the destination is at least on the same filesystem as the queue. The results of calling this more than once for a given entry are undefined.
Atomically and durably discards the entry (returned by store) from the queue. The discarded data will be placed at the destination path (durably if possible), when one is provided. This should be much more efficient, and likely safer if the destination is at least on the same filesystem as the queue. The results of calling this more than once for a given entry are undefined.
next-likely-idclj
(next-likely-id {next :next-likely-id :as q})Returns a likely id for the next message stored in the q. No subsequent entry ids will be less than this value.
Returns a likely id for the next message stored in the q. No subsequent entry ids will be less than this value.
openclj
(open directory)Opens the queue in directory, and returns it. Expects only stockpile created files in the directory, and currently deletes any existing file in the queue whose name starts with "tmp-".
Opens the queue in directory, and returns it. Expects only stockpile created files in the directory, and currently deletes any existing file in the queue whose name starts with "tmp-".
reduceclj
(reduce q f val)Calls (f reduction entry) for each existing entry as-per reduce, with val as the initial reduction, and returns the result. The ordering of the calls is unspecified, as is the effect of concurrent discards. The reduction may be escaped by throwing a unique exception (cf. slingshot). For example: (reduce "foo" conj []).
Calls (f reduction entry) for each existing entry as-per reduce, with val as the initial reduction, and returns the result. The ordering of the calls is unspecified, as is the effect of concurrent discards. The reduction may be escaped by throwing a unique exception (cf. slingshot). For example: (reduce "foo" conj []).
storeclj
(store q stream)(store q stream metadata)Atomically and durably enqueues the content of stream, and returns an entry that can be used to refer to the content later. An ex-info exception of {:kind ::unable-to-commit :stream-data path} may be thrown if store was able to read the data from the stream, but unable to make it durable. If any other exception is thrown, the state of the stream is unknown. The :stream-data value will be a path to a file containing all of the data that was in the stream. Among other things, it's possible that ::unable-to-commit indicates the metadata was incompatible with the underlying filesystem (it was too long, couldn't be encoded, etc.). That's because the current implementation records the metadata in a file name corresponding to the entry, and may use up to 20 (Unicode Basic Latin block) characters of that file name for internal purposes. The remainder of the filename is available for the metadata, but the maximum length of that remainder depends on the platform and target filesystem. Many common filesystems now allow a file name to be up to 255 characters or bytes, and at least on Linux, the JVM converts the Unicode string path to a filesystem path using an encoding that depends on the locale, often choosing UTF-8. So assuming a UTF-8 encoding and a 255 byte maximum path length (e.g. ext4), after subtracting the 20 (UTF-8 encoded Basic Latin block) bytes reserved for internal use, there may be up to 235 bytes available for the metadata. Of course how many Unicode characters that will allow depends on their size when converted to UTF-8. Whenever there's an error, it's possible that the attempt to clean up may fail and leave behind a temporary file. In that case create throws an ex-info exception of {:kind ::path-cleanup-failure-after-error :path p :exception ex} with the exception produced by the original failure as the cause. To handle that possibility, callers may want to structure invocations with a nested try like this: (try (try+ (stock/create ...) (catch [:kind ::path-cleanup-failure-after-error] {:keys [path exception]} ;; Perhaps log or try to clean up the path more aggressively (throw (:cause &throw-context))) (catch SomeExceptionThatCausedCreateToFail ;; Reached for this exception whether or not there was a ;; cleanup failure ...) ...) Additionally, among other exceptions, the current implementation may throw any documented by java.nio.file.Files/move for an ATOMIC_MOVE within the same directory.
Atomically and durably enqueues the content of stream, and returns
an entry that can be used to refer to the content later. An ex-info
exception of {:kind ::unable-to-commit :stream-data path} may be
thrown if store was able to read the data from the stream, but
unable to make it durable. If any other exception is thrown, the
state of the stream is unknown. The :stream-data value will be a
path to a file containing all of the data that was in the stream.
Among other things, it's possible that ::unable-to-commit indicates
the metadata was incompatible with the underlying filesystem (it was
too long, couldn't be encoded, etc.). That's because the current
implementation records the metadata in a file name corresponding to
the entry, and may use up to 20 (Unicode Basic Latin block)
characters of that file name for internal purposes. The remainder
of the filename is available for the metadata, but the maximum
length of that remainder depends on the platform and target
filesystem. Many common filesystems now allow a file name to be up
to 255 characters or bytes, and at least on Linux, the JVM converts
the Unicode string path to a filesystem path using an encoding that
depends on the locale, often choosing UTF-8. So assuming a UTF-8
encoding and a 255 byte maximum path length (e.g. ext4), after
subtracting the 20 (UTF-8 encoded Basic Latin block) bytes reserved
for internal use, there may be up to 235 bytes available for the
metadata. Of course how many Unicode characters that will allow
depends on their size when converted to UTF-8. Whenever there's an
error, it's possible that the attempt to clean up may fail and leave
behind a temporary file. In that case create throws an ex-info
exception of {:kind ::path-cleanup-failure-after-error :path
p :exception ex} with the exception produced by the original failure
as the cause. To handle that possibility, callers may want to
structure invocations with a nested try like this:
(try
(try+
(stock/create ...)
(catch [:kind ::path-cleanup-failure-after-error]
{:keys [path exception]}
;; Perhaps log or try to clean up the path more aggressively
(throw (:cause &throw-context)))
(catch SomeExceptionThatCausedCreateToFail
;; Reached for this exception whether or not there was a
;; cleanup failure
...)
...)
Additionally, among other exceptions, the current implementation may
throw any documented by java.nio.file.Files/move for an ATOMIC_MOVE
within the same directory.streamclj
(stream q entry)Returns an unbuffered stream of the entry's data. Throws an ex-info exception of {:kind ::no-such-entry :entry e :source s} if the requested entry does not exist. Currently the :source will always be a Path.
Returns an unbuffered stream of the entry's data. Throws an
ex-info exception of {:kind ::no-such-entry :entry e :source s} if
the requested entry does not exist. Currently the :source will
always be a Path.cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close