Nippy 3.4.2
Released under the Eclipse Public License - v 1.0
The fastest serialization library for Clojure.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/nippy "3.4.2"]
Namespaces
taoensso.nippy
High-performance serialization library for Clojure.
Public variables and functions:
- *auto-freeze-compressor*
- *custom-readers*
- *freeze-fallback*
- *freeze-serializable-allowlist*
- *incl-metadata?*
- *thaw-serializable-allowlist*
- *thaw-xform*
- -cache-proxy
- aes128-cbc-encryptor
- aes128-encryptor
- aes128-gcm-encryptor
- allow-and-record-any-serializable-class-unsafe
- cache
- compress
- decompress
- decrypt
- default-freeze-serializable-allowlist
- default-thaw-serializable-allowlist
- encrypt
- extend-freeze
- extend-thaw
- fast-freeze
- fast-thaw
- freezable?
- freeze
- freeze-to-file
- freeze-to-out!
- freeze-to-string
- get-recorded-serializable-classes
- IFreezable
- IFreezableWithMeta
- inspect-ba
- lz4-compressor
- lzma2-compressor
- public-types-spec
- read-quarantined-serializable-object-unsafe!
- snappy-compressor
- stress-data
- thaw
- thaw-from-file
- thaw-from-in!
- thaw-from-resource
- thaw-from-string
- throw-unfreezable
- try-write-readable
- try-write-serializable
- write-id
- write-unfreezable
- zstd-compressor
taoensso.nippy.tools
Utils for community tools that want to add user-configurable Nippy support. +Nippy 3.5.0-RC1 Generated by Codox
Nippy 3.5.0-RC1
\ No newline at end of file diff --git a/taoensso.nippy.html b/taoensso.nippy.html index c35cb79..a0458d4 100644 --- a/taoensso.nippy.html +++ b/taoensso.nippy.html @@ -1,6 +1,6 @@ -Nippy 3.5.0-RC1
Released under the Eclipse Public License - v 1.0
The fastest serialization library for Clojure.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/nippy "3.5.0-RC1"]Namespaces
taoensso.nippy
High-performance serialization library for Clojure.Public variables and functions:
- *auto-freeze-compressor*
- *custom-readers*
- *freeze-fallback*
- *freeze-serializable-allowlist*
- *incl-metadata?*
- *thaw-serializable-allowlist*
- *thaw-xform*
- -cache-proxy
- aes128-cbc-encryptor
- aes128-encryptor
- aes128-gcm-encryptor
- allow-and-record-any-serializable-class-unsafe
- cache
- compress
- decompress
- decrypt
- default-freeze-serializable-allowlist
- default-thaw-serializable-allowlist
- encrypt
- extend-freeze
- extend-thaw
- fast-freeze
- fast-thaw
- freezable?
- freeze
- freeze-to-file
- freeze-to-out!
- freeze-to-string
- get-recorded-serializable-classes
- IFreezable
- IFreezableWithMeta
- inspect-ba
- lz4-compressor
- lzma2-compressor
- public-types-spec
- read-quarantined-serializable-object-unsafe!
- snappy-compressor
- stress-data
- thaw
- thaw-from-file
- thaw-from-in!
- thaw-from-resource
- thaw-from-string
- throw-unfreezable
- try-write-readable
- try-write-serializable
- with-cache
- write-id
- write-unfreezable
- zstd-compressor
taoensso.nippy.tools
Utils for community tools that want to add user-configurable Nippy support. Used by Carmine, Faraday, etc.Public variables and functions:
taoensso.nippy documentation Generated by Codox
Nippy 3.4.2
taoensso.nippy
High-performance serialization library for Clojure. +taoensso.nippy documentation Generated by Codox
Nippy 3.5.0-RC1
taoensso.nippy
High-performance serialization library for Clojure.*auto-freeze-compressor*
dynamic
(fn [byte-array])->compressor used by `(freeze <x> {:compressor :auto}), nil => default*custom-readers*
dynamic
{<hash-or-byte-id> (fn [data-input])->read}*freeze-fallback*
dynamic
Controls Nippy's behaviour when trying to freeze an item for which Nippy @@ -268,9 +268,7 @@ then merge the recorded classes into Nippy's default allowlist/s, e.g.: (alter-var-root #'thaw-serializable-allowlist* (fn [_] (into default-thaw-serializable-allowlist - (keys (get-recorded-serializable-classes)))))cache
(cache x)Experimental, subject to change. Feedback welcome! - -Wraps value so that future writes of the same wrapped value with same + (keys (get-recorded-serializable-classes)))))cache
(cache x)Wraps value so that future writes of the same wrapped value with same metadata will be efficiently encoded as references to this one. (freeze [(cache "foo") (cache "foo") (cache "foo")]) @@ -302,17 +300,20 @@ NB: be careful about extending to interfaces, Ref. <fast-thaw
(fast-thaw ba)Like `thaw` but: - - Drops all support for compression and encryption +Equivalent to (but a little faster than) `freeze` with opts + {:no-header? true, :compressor nil, :encryptor nil}. + +Intended for use only by advanced users that clearly understand the tradeoffs. +I STRONGLY recommend that most users prefer the standard `freeze` since: + - The Nippy header is useful for data portability and preservation + - Compression is often benefitial at little/no cost + - The performance difference between `freeze` and `fast-freeze` is + often negligible in practice.fast-thaw
(fast-thaw ba)Like `thaw` but: - Supports only data frozen with `fast-freeze` + - Drops all support for compression and encryption Equivalent to (but a little faster than) `thaw` with opts: - - :compressor nil - - :encryptor nil - - :no-header? truefreezable?
(freezable? x)(freezable? x {:as opts, :keys [recursive? allow-clojure-reader? allow-java-serializable?], :or {recursive? true}})Alpha, subject to change. + {:no-header? true, :compressor nil, :encryptor nil}.freezable?
(freezable? x)(freezable? x {:as opts, :keys [recursive? allow-clojure-reader? allow-java-serializable?], :or {recursive? true}})Alpha, subject to change. Returns ∈ #{:native :maybe-clojure-reader :maybe-java-serializable nil}, truthy iff Nippy seems to support freezing for the given argument. @@ -337,14 +338,14 @@ Don't use this directly, instead see `extend-freeze`.inspect-ba
(inspect-ba ba)(inspect-ba ba thaw-opts)Experimental, subject to change. Feedback welcome!lz4-compressor
Default `LZ4` compressor: - Compression ratio: `C` (0.58 on reference benchmark). - - Compression speed: `A` (238 msecs on reference benchmark). - - Decompression speed: `A+` (31 msecs on reference benchmark). + - Compression speed: `A` (240 msecs on reference benchmark). + - Decompression speed: `A+` (30 msecs on reference benchmark). Good general-purpose compressor, favours speed. See `taoensso.nippy-benchmarks` for detailed comparative benchmarks.lzma2-compressor
Default `LZMA2` compressor: - Compression ratio: `A+` (0.4 on reference benchmark). - Compression speed: `E` (18.5 secs on reference benchmark). - - Decompression speed: `D` (11.8 secs on reference benchmark). + - Decompression speed: `D` (12 secs on reference benchmark). Specialized compressor, strongly favours ratio. See `taoensso.nippy-benchmarks` for detailed comparative benchmarks.public-types-spec
Public representation of Nippy's internal type schema. @@ -372,14 +373,14 @@ Format: - `payload-spec` examples: - nil ; No spec available (e.g. unpredictable payload) - [] ; Type has no payload - - [[:bytes 4]] ; Type has a payload of exactly 4 bytes - - [[:bytes 2] [:elements 2]] ; Type has a payload of exactly 2 bytes, then - ; 2 elements + - [[:bytes 4]] ; Type has payload of exactly 4 bytes + - [[:bytes 2] [:elements 2]] ; Type has payload of exactly 2 bytes, + ; followed by 2 elements - [[:bytes {:read 2}] [:elements {:read 4 :multiplier 2 :unsigned? true}]] - ; Type has payload of <short-count> bytes, then + ; Type has payload of <short-count> bytes, followed by ; <unsigned-int-count>*2 (multiplier) elements Note that `payload-spec` can be handy for skipping over items in @@ -392,8 +393,8 @@ to not contain any malicious code. See `*thaw-serializable-allowlist*` for more info.snappy-compressor
Default `Snappy` compressor: - Compression ratio: `C` (0.58 on reference benchmark). - - Compression speed: `A+` (206 msecs on reference benchmark). - - Decompression speed: `B` (134 msecs on reference benchmark). + - Compression speed: `A+` (210 msecs on reference benchmark). + - Decompression speed: `B` (130 msecs on reference benchmark). Good general-purpose compressor, favours speed. See `taoensso.nippy-benchmarks` for detailed comparative benchmarks.stress-data
(stress-data {:keys [comparable?], :as opts})Returns map of reference stress data for use by tests, benchmarks, etc.thaw
(thaw ba)(thaw ba {:as opts, :keys [v1-compatibility? compressor encryptor password serializable-allowlist incl-metadata? thaw-xform], :or {compressor :auto, encryptor :auto}})Deserializes a frozen Nippy byte array to its original Clojure data type. @@ -412,7 +413,12 @@ data type. This is a low-level util: in most cases you'll want `thaw` instead.thaw-from-resource
(thaw-from-resource res)(thaw-from-resource res thaw-opts)Convenience util: like `thaw`, but reads from `(clojure.java.io/resource <res>)`.thaw-from-string
(thaw-from-string s)(thaw-from-string s thaw-opts)Convenience util: like `thaw`, but takes a Base64-encoded string. -See also `freeze-to-string`.throw-unfreezable
(throw-unfreezable x)try-write-readable
(try-write-readable out x)try-write-serializable
(try-write-serializable out x)write-id
macro
(write-id out id)write-unfreezable
(write-unfreezable out x)zstd-compressor
Default `Zstd` (`Zstandard`) compressor: +See also `freeze-to-string`.throw-unfreezable
(throw-unfreezable x)try-write-readable
(try-write-readable out x)try-write-serializable
(try-write-serializable out x)with-cache
macro
(with-cache & body)Executes body with support for freezing/thawing cached values. + +This is a low-level util: you won't need to use this yourself unless +you're using `freeze-to-out!` or `thaw-from-in!` (also low-level utils). + +See also `cache`.write-id
macro
(write-id out id)write-unfreezable
(write-unfreezable out x)zstd-compressor
Default `Zstd` (`Zstandard`) compressor: - Compression ratio: `B` (0.53 on reference benchmark). - Compression speed: `C` (1300 msecs on reference benchmark). - Decompression speed: `B` (400 msecs on reference benchmark). diff --git a/taoensso.nippy.tools.html b/taoensso.nippy.tools.html index 5f2404e..a1f830c 100644 --- a/taoensso.nippy.tools.html +++ b/taoensso.nippy.tools.html @@ -1,6 +1,6 @@ -taoensso.nippy.tools documentation Generated by Codox
Nippy 3.4.2
taoensso.nippy.tools
Utils for community tools that want to add user-configurable Nippy support. +taoensso.nippy.tools documentation Generated by Codox
Nippy 3.5.0-RC1
taoensso.nippy.tools
Utils for community tools that want to add user-configurable Nippy support. Used by Carmine, Faraday, etc.*freeze-opts*
dynamic
*thaw-opts*
dynamic
freeze
(freeze x)(freeze x default-opts)Like `nippy/freeze` but uses as options the following, merged in order of ascending preference: