[ViewVC] Diff of: cvs/CBOR-XS/README

Comparing CBOR-XS/README (file contents):
Revision 1.8 by root, Tue Oct 29 22:04:52 2013 UTC vs.
Revision 1.18 by root, Wed Dec 7 14:14:30 2016 UTC

…		…
21	# data was decoded	21	# data was decoded
22	substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string	22	substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
23	}	23	}
24		24
25	DESCRIPTION	25	DESCRIPTION
26	WARNING! This module is very new, and not very well tested (that's up to
27	you to do). Furthermore, details of the implementation might change
28	freely before version 1.0. And lastly, the object serialisation protocol
29	depends on a pending IANA assignment, and until that assignment is
30	official, this implementation is not interoperable with other
31	implementations (even future versions of this module) until the
32	assignment is done.
33
34	You are still invited to try out CBOR, and this module.
35
36	This module converts Perl data structures to the Concise Binary Object	26	This module converts Perl data structures to the Concise Binary Object
37	Representation (CBOR) and vice versa. CBOR is a fast binary	27	Representation (CBOR) and vice versa. CBOR is a fast binary
38	serialisation format that aims to use a superset of the JSON data model,	28	serialisation format that aims to use an (almost) superset of the JSON
39	i.e. when you can represent something in JSON, you should be able to	29	data model, i.e. when you can represent something useful in JSON, you
40	represent it in CBOR.	30	should be able to represent it in CBOR.
41		31
42	In short, CBOR is a faster and very compact binary alternative to JSON,	32	In short, CBOR is a faster and quite compact binary alternative to JSON,
43	with the added ability of supporting serialisation of Perl objects.	33	with the added ability of supporting serialisation of Perl objects.
44	(JSON often compresses better than CBOR though, so if you plan to	34	(JSON often compresses better than CBOR though, so if you plan to
45	compress the data later you might want to compare both formats first).	35	compress the data later and speed is less important you might want to
		36	compare both formats first).
46		37
47	To give you a general idea about speed, with texts in the megabyte	38	To give you a general idea about speed, with texts in the megabyte
48	range, "CBOR::XS" usually encodes roughly twice as fast as Storable or	39	range, "CBOR::XS" usually encodes roughly twice as fast as Storable or
49	JSON::XS and decodes about 15%-30% faster than those. The shorter the	40	JSON::XS and decodes about 15%-30% faster than those. The shorter the
50	data, the worse Storable performs in comparison.	41	data, the worse Storable performs in comparison.
51		42
52	As for compactness, "CBOR::XS" encoded data structures are usually about	43	Regarding compactness, "CBOR::XS"-encoded data structures are usually
53	20% smaller than the same data encoded as (compact) JSON or Storable.	44	about 20% smaller than the same data encoded as (compact) JSON or
		45	Storable.
		46
		47	In addition to the core CBOR data format, this module implements a
		48	number of extensions, to support cyclic and shared data structures (see
		49	"allow_sharing" and "allow_cycles"), string deduplication (see
		50	"pack_strings") and scalar references (always enabled).
54		51
55	The primary goal of this module is to be correct and the secondary	52	The primary goal of this module is to be correct and the secondary
56	goal is to be fast. To reach the latter goal it was written in C.	53	goal is to be fast. To reach the latter goal it was written in C.
57		54
58	See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and	55	See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
…		…
80	disabled.	77	disabled.
81		78
82	The mutators for flags all return the CBOR object again and thus	79	The mutators for flags all return the CBOR object again and thus
83	calls can be chained:	80	calls can be chained:
84		81
85	#TODO my $cbor = CBOR::XS->new->encode ({a => [1,2]});	82	my $cbor = CBOR::XS->new->encode ({a => [1,2]});
		83
		84	$cbor = new_safe CBOR::XS
		85	Create a new, safe/secure CBOR::XS object. This is similar to "new",
		86	but configures the coder object to be safe to use with untrusted
		87	data. Currently, this is equivalent to:
		88
		89	my $cbor = CBOR::XS
		90	->new
		91	->forbid_objects
		92	->filter (\&CBOR::XS::safe_filter)
		93	->max_size (1e8);
		94
		95	But is more future proof (it is better to crash because of a change
		96	than to be exploited in other ways).
86		97
87	$cbor = $cbor->max_depth ([$maximum_nesting_depth])	98	$cbor = $cbor->max_depth ([$maximum_nesting_depth])
88	$max_depth = $cbor->get_max_depth	99	$max_depth = $cbor->get_max_depth
89	Sets the maximum nesting level (default 512) accepted while encoding	100	Sets the maximum nesting level (default 512) accepted while encoding
90	or decoding. If a higher nesting level is detected in CBOR data or a	101	or decoding. If a higher nesting level is detected in CBOR data or a
…		…
104		115
105	Note that nesting is implemented by recursion in C. The default	116	Note that nesting is implemented by recursion in C. The default
106	value has been chosen to be as large as typical operating systems	117	value has been chosen to be as large as typical operating systems
107	allow without crashing.	118	allow without crashing.
108		119
109	See SECURITY CONSIDERATIONS, below, for more info on why this is	120	See "SECURITY CONSIDERATIONS", below, for more info on why this is
110	useful.	121	useful.
111		122
112	$cbor = $cbor->max_size ([$maximum_string_size])	123	$cbor = $cbor->max_size ([$maximum_string_size])
113	$max_size = $cbor->get_max_size	124	$max_size = $cbor->get_max_size
114	Set the maximum length a CBOR string may have (in bytes) where	125	Set the maximum length a CBOR string may have (in bytes) where
…		…
118	exception. This setting has no effect on "encode" (yet).	129	exception. This setting has no effect on "encode" (yet).
119		130
120	If no argument is given, the limit check will be deactivated (same	131	If no argument is given, the limit check will be deactivated (same
121	as when 0 is specified).	132	as when 0 is specified).
122		133
123	See SECURITY CONSIDERATIONS, below, for more info on why this is	134	See "SECURITY CONSIDERATIONS", below, for more info on why this is
124	useful.	135	useful.
		136
		137	$cbor = $cbor->allow_unknown ([$enable])
		138	$enabled = $cbor->get_allow_unknown
		139	If $enable is true (or missing), then "encode" will not throw an
		140	exception when it encounters values it cannot represent in CBOR (for
		141	example, filehandles) but instead will encode a CBOR "error" value.
		142
		143	If $enable is false (the default), then "encode" will throw an
		144	exception when it encounters anything it cannot encode as CBOR.
		145
		146	This option does not affect "decode" in any way, and it is
		147	recommended to leave it off unless you know your communications
		148	partner.
		149
		150	$cbor = $cbor->allow_sharing ([$enable])
		151	$enabled = $cbor->get_allow_sharing
		152	If $enable is true (or missing), then "encode" will not
		153	double-encode values that have been referenced before (e.g. when the
		154	same object, such as an array, is referenced multiple times), but
		155	instead will emit a reference to the earlier value.
		156
		157	This means that such values will only be encoded once, and will not
		158	result in a deep cloning of the value on decode, in decoders
		159	supporting the value sharing extension. This also makes it possible
		160	to encode cyclic data structures (which need "allow_cycles" to be
		161	enabled to be decoded by this module).
		162
		163	It is recommended to leave it off unless you know your communication
		164	partner supports the value sharing extensions to CBOR
		165	(<http://cbor.schmorp.de/value-sharing>), as without decoder
		166	support, the resulting data structure might be unusable.
		167
		168	Detecting shared values incurs a runtime overhead when values are
		169	encoded that have a reference counter large than one, and might
		170	unnecessarily increase the encoded size, as potentially shared
		171	values are encode as shareable whether or not they are actually
		172	shared.
		173
		174	At the moment, only targets of references can be shared (e.g.
		175	scalars, arrays or hashes pointed to by a reference). Weirder
		176	constructs, such as an array with multiple "copies" of the same
		177	string, which are hard but not impossible to create in Perl, are not
		178	supported (this is the same as with Storable).
		179
		180	If $enable is false (the default), then "encode" will encode shared
		181	data structures repeatedly, unsharing them in the process. Cyclic
		182	data structures cannot be encoded in this mode.
		183
		184	This option does not affect "decode" in any way - shared values and
		185	references will always be decoded properly if present.
		186
		187	$cbor = $cbor->allow_cycles ([$enable])
		188	$enabled = $cbor->get_allow_cycles
		189	If $enable is true (or missing), then "decode" will happily decode
		190	self-referential (cyclic) data structures. By default these will not
		191	be decoded, as they need manual cleanup to avoid memory leaks, so
		192	code that isn't prepared for this will not leak memory.
		193
		194	If $enable is false (the default), then "decode" will throw an error
		195	when it encounters a self-referential/cyclic data structure.
		196
		197	FUTURE DIRECTION: the motivation behind this option is to avoid
		198	real cycles - future versions of this module might chose to decode
		199	cyclic data structures using weak references when this option is
		200	off, instead of throwing an error.
		201
		202	This option does not affect "encode" in any way - shared values and
		203	references will always be encoded properly if present.
		204
		205	$cbor = $cbor->forbid_objects ([$enable])
		206	$enabled = $cbor->get_forbid_objects
		207	Disables the use of the object serialiser protocol.
		208
		209	If $enable is true (or missing), then "encode" will will throw an
		210	exception when it encounters perl objects that would be encoded
		211	using the perl-object tag (26). When "decode" encounters such tags,
		212	it will fall back to the general filter/tagged logic as if this were
		213	an unknown tag (by default resulting in a "CBOR::XC::Tagged"
		214	object).
		215
		216	If $enable is false (the default), then "encode" will use the
		217	Types::Serialiser object serialisation protocol to serialise objects
		218	into perl-object tags, and "decode" will do the same to decode such
		219	tags.
		220
		221	See "SECURITY CONSIDERATIONS", below, for more info on why
		222	forbidding this protocol can be useful.
		223
		224	$cbor = $cbor->pack_strings ([$enable])
		225	$enabled = $cbor->get_pack_strings
		226	If $enable is true (or missing), then "encode" will try not to
		227	encode the same string twice, but will instead encode a reference to
		228	the string instead. Depending on your data format, this can save a
		229	lot of space, but also results in a very large runtime overhead
		230	(expect encoding times to be 2-4 times as high as without).
		231
		232	It is recommended to leave it off unless you know your
		233	communications partner supports the stringref extension to CBOR
		234	(<http://cbor.schmorp.de/stringref>), as without decoder support,
		235	the resulting data structure might not be usable.
		236
		237	If $enable is false (the default), then "encode" will encode strings
		238	the standard CBOR way.
		239
		240	This option does not affect "decode" in any way - string references
		241	will always be decoded properly if present.
		242
		243	$cbor = $cbor->text_keys ([$enable])
		244	$enabled = $cbor->get_text_keys
		245	If $enabled is true (or missing), then "encode" will encode all perl
		246	hash keys as CBOR text strings/UTF-8 string, upgrading them as
		247	needed.
		248
		249	If $enable is false (the default), then "encode" will encode hash
		250	keys normally - upgraded perl strings (strings internally encoded as
		251	UTF-8) as CBOR text strings, and downgraded perl strings as CBOR
		252	byte strings.
		253
		254	This option does not affect "decode" in any way.
		255
		256	This option is useful for interoperability with CBOR decoders that
		257	don't treat byte strings as a form of text. It is especially useful
		258	as Perl gives very little control over hash keys.
		259
		260	Enabling this option can be slow, as all downgraded hash keys that
		261	are encoded need to be scanned and converted to UTF-8.
		262
		263	$cbor = $cbor->text_strings ([$enable])
		264	$enabled = $cbor->get_text_strings
		265	This option works similar to "text_keys", above, but works on all
		266	strings (including hash keys), so "text_keys" has no further effect
		267	after enabling "text_strings".
		268
		269	If $enabled is true (or missing), then "encode" will encode all perl
		270	strings as CBOR text strings/UTF-8 strings, upgrading them as
		271	needed.
		272
		273	If $enable is false (the default), then "encode" will encode strings
		274	normally (but see "text_keys") - upgraded perl strings (strings
		275	internally encoded as UTF-8) as CBOR text strings, and downgraded
		276	perl strings as CBOR byte strings.
		277
		278	This option does not affect "decode" in any way.
		279
		280	This option has similar advantages and disadvantages as "text_keys".
		281	In addition, this option effectively removes the ability to encode
		282	byte strings, which might break some "FREEZE" and "TO_CBOR" methods
		283	that rely on this, such as bignum encoding, so this option is mainly
		284	useful for very simple data.
		285
		286	$cbor = $cbor->validate_utf8 ([$enable])
		287	$enabled = $cbor->get_validate_utf8
		288	If $enable is true (or missing), then "decode" will validate that
		289	elements (text strings) containing UTF-8 data in fact contain valid
		290	UTF-8 data (instead of blindly accepting it). This validation
		291	obviously takes extra time during decoding.
		292
		293	The concept of "valid UTF-8" used is perl's concept, which is a
		294	superset of the official UTF-8.
		295
		296	If $enable is false (the default), then "decode" will blindly accept
		297	UTF-8 data, marking them as valid UTF-8 in the resulting data
		298	structure regardless of whether that's true or not.
		299
		300	Perl isn't too happy about corrupted UTF-8 in strings, but should
		301	generally not crash or do similarly evil things. Extensions might be
		302	not so forgiving, so it's recommended to turn on this setting if you
		303	receive untrusted CBOR.
		304
		305	This option does not affect "encode" in any way - strings that are
		306	supposedly valid UTF-8 will simply be dumped into the resulting CBOR
		307	string without checking whether that is, in fact, true or not.
		308
		309	$cbor = $cbor->filter ([$cb->($tag, $value)])
		310	$cb_or_undef = $cbor->get_filter
		311	Sets or replaces the tagged value decoding filter (when $cb is
		312	specified) or clears the filter (if no argument or "undef" is
		313	provided).
		314
		315	The filter callback is called only during decoding, when a
		316	non-enforced tagged value has been decoded (see "TAG HANDLING AND
		317	EXTENSIONS" for a list of enforced tags). For specific tags, it's
		318	often better to provide a default converter using the
		319	%CBOR::XS::FILTER hash (see below).
		320
		321	The first argument is the numerical tag, the second is the (decoded)
		322	value that has been tagged.
		323
		324	The filter function should return either exactly one value, which
		325	will replace the tagged value in the decoded data structure, or no
		326	values, which will result in default handling, which currently means
		327	the decoder creates a "CBOR::XS::Tagged" object to hold the tag and
		328	the value.
		329
		330	When the filter is cleared (the default state), the default filter
		331	function, "CBOR::XS::default_filter", is used. This function simply
		332	looks up the tag in the %CBOR::XS::FILTER hash. If an entry exists
		333	it must be a code reference that is called with tag and value, and
		334	is responsible for decoding the value. If no entry exists, it
		335	returns no values. "CBOR::XS" provides a number of default filter
		336	functions already, the the %CBOR::XS::FILTER hash can be freely
		337	extended with more.
		338
		339	"CBOR::XS" additionally provides an alternative filter function that
		340	is supposed to be safe to use with untrusted data (which the default
		341	filter might not), called "CBOR::XS::safe_filter", which works the
		342	same as the "default_filter" but uses the %CBOR::XS::SAFE_FILTER
		343	variable instead. It is prepopulated with the tag decoding functions
		344	that are deemed safe (basically the same as %CBOR::XS::FILTER
		345	without all the bignum tags), and can be extended by user code as
		346	wlel, although, obviously, one should be very careful about adding
		347	decoding functions here, since the expectation is that they are safe
		348	to use on untrusted data, after all.
		349
		350	Example: decode all tags not handled internally into
		351	"CBOR::XS::Tagged" objects, with no other special handling (useful
		352	when working with potentially "unsafe" CBOR data).
		353
		354	CBOR::XS->new->filter (sub { })->decode ($cbor_data);
		355
		356	Example: provide a global filter for tag 1347375694, converting the
		357	value into some string form.
		358
		359	$CBOR::XS::FILTER{1347375694} = sub {
		360	my ($tag, $value);
		361
		362	"tag 1347375694 value $value"
		363	};
		364
		365	Example: provide your own filter function that looks up tags in your
		366	own hash:
		367
		368	my %my_filter = (
		369	998347484 => sub {
		370	my ($tag, $value);
		371
		372	"tag 998347484 value $value"
		373	};
		374	);
		375
		376	my $coder = CBOR::XS->new->filter (sub {
		377	&{ $my_filter{$_[0]} or return }
		378	});
		379
		380	Example: use the safe filter function (see "SECURITY CONSIDERATIONS"
		381	for more considerations on security).
		382
		383	CBOR::XS->new->filter (\&CBOR::XS::safe_filter)->decode ($cbor_data);
125		384
126	$cbor_data = $cbor->encode ($perl_scalar)	385	$cbor_data = $cbor->encode ($perl_scalar)
127	Converts the given Perl data structure (a scalar value) to its CBOR	386	Converts the given Perl data structure (a scalar value) to its CBOR
128	representation.	387	representation.
129		388
…		…
142	the next one starts.	401	the next one starts.
143		402
144	CBOR::XS->new->decode_prefix ("......")	403	CBOR::XS->new->decode_prefix ("......")
145	=> ("...", 3)	404	=> ("...", 3)
146		405
		406	INCREMENTAL PARSING
		407	In some cases, there is the need for incremental parsing of JSON texts.
		408	While this module always has to keep both CBOR text and resulting Perl
		409	data structure in memory at one time, it does allow you to parse a CBOR
		410	stream incrementally, using a similar to using "decode_prefix" to see if
		411	a full CBOR object is available, but is much more efficient.
		412
		413	It basically works by parsing as much of a CBOR string as possible - if
		414	the CBOR data is not complete yet, the pasrer will remember where it
		415	was, to be able to restart when more data has been accumulated. Once
		416	enough data is available to either decode a complete CBOR value or raise
		417	an error, a real decode will be attempted.
		418
		419	A typical use case would be a network protocol that consists of sending
		420	and receiving CBOR-encoded messages. The solution that works with CBOR
		421	and about anything else is by prepending a length to every CBOR value,
		422	so the receiver knows how many octets to read. More compact (and
		423	slightly slower) would be to just send CBOR values back-to-back, as
		424	"CBOR::XS" knows where a CBOR value ends, and doesn't need an explicit
		425	length.
		426
		427	The following methods help with this:
		428
		429	@decoded = $cbor->incr_parse ($buffer)
		430	This method attempts to decode exactly one CBOR value from the
		431	beginning of the given $buffer. The value is removed from the
		432	$buffer on success. When $buffer doesn't contain a complete value
		433	yet, it returns nothing. Finally, when the $buffer doesn't start
		434	with something that could ever be a valid CBOR value, it raises an
		435	exception, just as "decode" would. In the latter case the decoder
		436	state is undefined and must be reset before being able to parse
		437	further.
		438
		439	This method modifies the $buffer in place. When no CBOR value can be
		440	decoded, the decoder stores the current string offset. On the next
		441	call, continues decoding at the place where it stopped before. For
		442	this to make sense, the $buffer must begin with the same octets as
		443	on previous unsuccessful calls.
		444
		445	You can call this method in scalar context, in which case it either
		446	returns a decoded value or "undef". This makes it impossible to
		447	distinguish between CBOR null values (which decode to "undef") and
		448	an unsuccessful decode, which is often acceptable.
		449
		450	@decoded = $cbor->incr_parse_multiple ($buffer)
		451	Same as "incr_parse", but attempts to decode as many CBOR values as
		452	possible in one go, instead of at most one. Calls to "incr_parse"
		453	and "incr_parse_multiple" can be interleaved.
		454
		455	$cbor->incr_reset
		456	Resets the incremental decoder. This throws away any saved state, so
		457	that subsequent calls to "incr_parse" or "incr_parse_multiple" start
		458	to parse a new CBOR value from the beginning of the $buffer again.
		459
		460	This method can be called at any time, but it must be called if
		461	you want to change your $buffer or there was a decoding error and
		462	you want to reuse the $cbor object for future incremental parsings.
		463
147	MAPPING	464	MAPPING
148	This section describes how CBOR::XS maps Perl values to CBOR values and	465	This section describes how CBOR::XS maps Perl values to CBOR values and
149	vice versa. These mappings are designed to "do the right thing" in most	466	vice versa. These mappings are designed to "do the right thing" in most
150	circumstances automatically, preserving round-tripping characteristics	467	circumstances automatically, preserving round-tripping characteristics
151	(what you put in comes out as something equivalent).	468	(what you put in comes out as something equivalent).
…		…
158	integers	475	integers
159	CBOR integers become (numeric) perl scalars. On perls without 64 bit	476	CBOR integers become (numeric) perl scalars. On perls without 64 bit
160	support, 64 bit integers will be truncated or otherwise corrupted.	477	support, 64 bit integers will be truncated or otherwise corrupted.
161		478
162	byte strings	479	byte strings
163	Byte strings will become octet strings in Perl (the byte values	480	Byte strings will become octet strings in Perl (the Byte values
164	0..255 will simply become characters of the same value in Perl).	481	0..255 will simply become characters of the same value in Perl).
165		482
166	UTF-8 strings	483	UTF-8 strings
167	UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be	484	UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
168	decoded into proper Unicode code points. At the moment, the validity	485	decoded into proper Unicode code points. At the moment, the validity
…		…
182	"Types:Serialiser::false" and "Types::Serialiser::error",	499	"Types:Serialiser::false" and "Types::Serialiser::error",
183	respectively. They are overloaded to act almost exactly like the	500	respectively. They are overloaded to act almost exactly like the
184	numbers 1 and 0 (for true and false) or to throw an exception on	501	numbers 1 and 0 (for true and false) or to throw an exception on
185	access (for error). See the Types::Serialiser manpage for details.	502	access (for error). See the Types::Serialiser manpage for details.
186		503
187	CBOR tag 256 (perl object)	504	tagged values
188	The tag value 256 (TODO: pending iana registration) will be used to
189	deserialise a Perl object serialised with "FREEZE". See OBJECT
190	SERIALISATION, below, for details.
191
192	CBOR tag 55799 (magic header)
193	The tag 55799 is ignored (this tag implements the magic header).
194
195	other CBOR tags
196	Tagged items consists of a numeric tag and another CBOR value. Tags	505	Tagged items consists of a numeric tag and another CBOR value.
197	not handled internally are currently converted into a
198	CBOR::XS::Tagged object, which is simply a blessed array reference
199	consisting of the numeric tag value followed by the (decoded) CBOR
200	value.
201		506
202	In the future, support for user-supplied conversions might get	507	See "TAG HANDLING AND EXTENSIONS" and the description of "->filter"
203	added.	508	for details on which tags are handled how.
204		509
205	anything else	510	anything else
206	Anything else (e.g. unsupported simple values) will raise a decoding	511	Anything else (e.g. unsupported simple values) will raise a decoding
207	error.	512	error.
208		513
209	PERL -> CBOR	514	PERL -> CBOR
210	The mapping from Perl to CBOR is slightly more difficult, as Perl is a	515	The mapping from Perl to CBOR is slightly more difficult, as Perl is a
211	truly typeless language, so we can only guess which CBOR type is meant	516	typeless language. That means this module can only guess which CBOR type
212	by a Perl value.	517	is meant by a perl value.
213		518
214	hash references	519	hash references
215	Perl hash references become CBOR maps. As there is no inherent	520	Perl hash references become CBOR maps. As there is no inherent
216	ordering in hash keys (or CBOR maps), they will usually be encoded	521	ordering in hash keys (or CBOR maps), they will usually be encoded
217	in a pseudo-random order.	522	in a pseudo-random order. This order can be different each time a
		523	hash is encoded.
218		524
219	Currently, tied hashes will use the indefinite-length format, while	525	Currently, tied hashes will use the indefinite-length format, while
220	normal hashes will use the fixed-length format.	526	normal hashes will use the fixed-length format.
221		527
222	array references	528	array references
223	Perl array references become fixed-length CBOR arrays.	529	Perl array references become fixed-length CBOR arrays.
224		530
225	other references	531	other references
226	Other unblessed references are generally not allowed and will cause	532	Other unblessed references will be represented using the indirection
227	an exception to be thrown, except for references to the integers 0	533	tag extension (tag value 22098,
228	and 1, which get turned into false and true in CBOR.	534	<http://cbor.schmorp.de/indirection>). CBOR decoders are guaranteed
		535	to be able to decode these values somehow, by either "doing the
		536	right thing", decoding into a generic tagged object, simply ignoring
		537	the tag, or something else.
229		538
230	CBOR::XS::Tagged objects	539	CBOR::XS::Tagged objects
231	Objects of this type must be arrays consisting of a single "[tag,	540	Objects of this type must be arrays consisting of a single "[tag,
232	value]" pair. The (numerical) tag will be encoded as a CBOR tag, the	541	value]" pair. The (numerical) tag will be encoded as a CBOR tag, the
233	value will be encoded as appropriate for the value. You cna use	542	value will be encoded as appropriate for the value. You must use
234	"CBOR::XS::tag" to create such objects.	543	"CBOR::XS::tag" to create such objects.
235		544
236	Types::Serialiser::true, Types::Serialiser::false,	545	Types::Serialiser::true, Types::Serialiser::false,
237	Types::Serialiser::error	546	Types::Serialiser::error
238	These special values become CBOR true, CBOR false and CBOR undefined	547	These special values become CBOR true, CBOR false and CBOR undefined
239	values, respectively. You can also use "\1", "\0" and "\undef"	548	values, respectively. You can also use "\1", "\0" and "\undef"
240	directly if you want.	549	directly if you want.
241		550
242	other blessed objects	551	other blessed objects
243	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See	552	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
244	"OBJECT SERIALISATION", below, for details.	553	"TAG HANDLING AND EXTENSIONS" for specific classes handled by this
		554	module, and "OBJECT SERIALISATION" for generic object serialisation.
245		555
246	simple scalars	556	simple scalars
247	TODO Simple Perl scalars (any scalar that is not a reference) are	557	Simple Perl scalars (any scalar that is not a reference) are the
248	the most difficult objects to encode: CBOR::XS will encode undefined	558	most difficult objects to encode: CBOR::XS will encode undefined
249	scalars as CBOR null values, scalars that have last been used in a	559	scalars as CBOR null values, scalars that have last been used in a
250	string context before encoding as CBOR strings, and anything else as	560	string context before encoding as CBOR strings, and anything else as
251	number value:	561	number value:
252		562
253	# dump as number	563	# dump as number
254	encode_cbor [2] # yields [2]	564	encode_cbor [2] # yields [2]
255	encode_cbor [-3.0e17] # yields [-3e+17]	565	encode_cbor [-3.0e17] # yields [-3e+17]
256	my $value = 5; encode_cbor [$value] # yields [5]	566	my $value = 5; encode_cbor [$value] # yields [5]
257		567
258	# used as string, so dump as string	568	# used as string, so dump as string (either byte or text)
259	print $value;	569	print $value;
260	encode_cbor [$value] # yields ["5"]	570	encode_cbor [$value] # yields ["5"]
261		571
262	# undef becomes null	572	# undef becomes null
263	encode_cbor [undef] # yields [null]	573	encode_cbor [undef] # yields [null]
…		…
266		576
267	my $x = 3.1; # some variable containing a number	577	my $x = 3.1; # some variable containing a number
268	"$x"; # stringified	578	"$x"; # stringified
269	$x .= ""; # another, more awkward way to stringify	579	$x .= ""; # another, more awkward way to stringify
270	print $x; # perl does it for you, too, quite often	580	print $x; # perl does it for you, too, quite often
		581
		582	You can force whether a string is encoded as byte or text string by
		583	using "utf8::upgrade" and "utf8::downgrade" (if "text_strings" is
		584	disabled):
		585
		586	utf8::upgrade $x; # encode $x as text string
		587	utf8::downgrade $x; # encode $x as byte string
		588
		589	Perl doesn't define what operations up- and downgrade strings, so if
		590	the difference between byte and text is important, you should up- or
		591	downgrade your string as late as possible before encoding. You can
		592	also force the use of CBOR text strings by using "text_keys" or
		593	"text_strings".
271		594
272	You can force the type to be a CBOR number by numifying it:	595	You can force the type to be a CBOR number by numifying it:
273		596
274	my $x = "3"; # some variable containing a string	597	my $x = "3"; # some variable containing a string
275	$x += 0; # numify it, ensuring it will be dumped as a number	598	$x += 0; # numify it, ensuring it will be dumped as a number
…		…
285	the IEEE double format will be used. Perls that use formats other	608	the IEEE double format will be used. Perls that use formats other
286	than IEEE double to represent numerical values are supported, but	609	than IEEE double to represent numerical values are supported, but
287	might suffer loss of precision.	610	might suffer loss of precision.
288		611
289	OBJECT SERIALISATION	612	OBJECT SERIALISATION
		613	This module implements both a CBOR-specific and the generic
		614	Types::Serialier object serialisation protocol. The following
		615	subsections explain both methods.
		616
		617	ENCODING
290	This module knows two way to serialise a Perl object: The CBOR-specific	618	This module knows two way to serialise a Perl object: The CBOR-specific
291	way, and the generic way.	619	way, and the generic way.
292		620
293	Whenever the encoder encounters a Perl object that it cnanot serialise	621	Whenever the encoder encounters a Perl object that it cannot serialise
294	directly (most of them), it will first look up the "TO_CBOR" method on	622	directly (most of them), it will first look up the "TO_CBOR" method on
295	it.	623	it.
296		624
297	If it has a "TO_CBOR" method, it will call it with the object as only	625	If it has a "TO_CBOR" method, it will call it with the object as only
298	argument, and expects exactly one return value, which it will then	626	argument, and expects exactly one return value, which it will then
…		…
303	"CBOR" as the second argument, to distinguish it from other serialisers.	631	"CBOR" as the second argument, to distinguish it from other serialisers.
304		632
305	The "FREEZE" method can return any number of values (i.e. zero or more).	633	The "FREEZE" method can return any number of values (i.e. zero or more).
306	These will be encoded as CBOR perl object, together with the classname.	634	These will be encoded as CBOR perl object, together with the classname.
307		635
		636	These methods MUST NOT change the data structure that is being
		637	serialised. Failure to comply to this can result in memory corruption -
		638	and worse.
		639
308	If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail	640	If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail
309	with an error.	641	with an error.
310		642
		643	DECODING
311	Objects encoded via "TO_CBOR" cannot be automatically decoded, but	644	Objects encoded via "TO_CBOR" cannot (normally) be automatically
312	objects encoded via "FREEZE" can be decoded using the following	645	decoded, but objects encoded via "FREEZE" can be decoded using the
313	protocol:	646	following protocol:
314		647
315	When an encoded CBOR perl object is encountered by the decoder, it will	648	When an encoded CBOR perl object is encountered by the decoder, it will
316	look up the "THAW" method, by using the stored classname, and will fail	649	look up the "THAW" method, by using the stored classname, and will fail
317	if the method cannot be found.	650	if the method cannot be found.
318		651
…		…
339		672
340	sub URI::TO_CBOR {	673	sub URI::TO_CBOR {
341	my ($self) = @_;	674	my ($self) = @_;
342	my $uri = "$self"; # stringify uri	675	my $uri = "$self"; # stringify uri
343	utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string	676	utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
344	CBOR::XS::tagged 32, "$_[0]"	677	CBOR::XS::tag 32, "$_[0]"
345	}	678	}
346		679
347	This will encode URIs as a UTF-8 string with tag 32, which indicates an	680	This will encode URIs as a UTF-8 string with tag 32, which indicates an
348	URI.	681	URI.
349		682
…		…
360	"$self" # encode url string	693	"$self" # encode url string
361	}	694	}
362		695
363	sub URI::THAW {	696	sub URI::THAW {
364	my ($class, $serialiser, $uri) = @_;	697	my ($class, $serialiser, $uri) = @_;
365
366	$class->new ($uri)	698	$class->new ($uri)
367	}	699	}
368		700
369	Unlike "TO_CBOR", multiple values can be returned by "FREEZE". For	701	Unlike "TO_CBOR", multiple values can be returned by "FREEZE". For
370	example, a "FREEZE" method that returns "type", "id" and "variant"	702	example, a "FREEZE" method that returns "type", "id" and "variant"
…		…
384		716
385	MAGIC HEADER	717	MAGIC HEADER
386	There is no way to distinguish CBOR from other formats programmatically.	718	There is no way to distinguish CBOR from other formats programmatically.
387	To make it easier to distinguish CBOR from other formats, the CBOR	719	To make it easier to distinguish CBOR from other formats, the CBOR
388	specification has a special "magic string" that can be prepended to any	720	specification has a special "magic string" that can be prepended to any
389	CBOR string without changing it's meaning.	721	CBOR string without changing its meaning.
390		722
391	This string is available as $CBOR::XS::MAGIC. This module does not	723	This string is available as $CBOR::XS::MAGIC. This module does not
392	prepend this string tot he CBOR data it generates, but it will ignroe it	724	prepend this string to the CBOR data it generates, but it will ignore it
393	if present, so users can prepend this string as a "file type" indicator	725	if present, so users can prepend this string as a "file type" indicator
394	as required.	726	as required.
395		727
396	THE CBOR::XS::Tagged CLASS	728	THE CBOR::XS::Tagged CLASS
397	CBOR has the concept of tagged values - any CBOR value can be tagged	729	CBOR has the concept of tagged values - any CBOR value can be tagged
…		…
448	Wrap CBOR data in CBOR:	780	Wrap CBOR data in CBOR:
449		781
450	my $cbor_cbor = encode_cbor	782	my $cbor_cbor = encode_cbor
451	CBOR::XS::tag 24,	783	CBOR::XS::tag 24,
452	encode_cbor [1, 2, 3];	784	encode_cbor [1, 2, 3];
		785
		786	TAG HANDLING AND EXTENSIONS
		787	This section describes how this module handles specific tagged values
		788	and extensions. If a tag is not mentioned here and no additional filters
		789	are provided for it, then the default handling applies (creating a
		790	CBOR::XS::Tagged object on decoding, and only encoding the tag when
		791	explicitly requested).
		792
		793	Tags not handled specifically are currently converted into a
		794	CBOR::XS::Tagged object, which is simply a blessed array reference
		795	consisting of the numeric tag value followed by the (decoded) CBOR
		796	value.
		797
		798	Future versions of this module reserve the right to special case
		799	additional tags (such as base64url).
		800
		801	ENFORCED TAGS
		802	These tags are always handled when decoding, and their handling cannot
		803	be overridden by the user.
		804
		805	26 (perl-object, <http://cbor.schmorp.de/perl-object>)
		806	These tags are automatically created (and decoded) for serialisable
		807	objects using the "FREEZE/THAW" methods (the Types::Serialier object
		808	serialisation protocol). See "OBJECT SERIALISATION" for details.
		809
		810	28, 29 (shareable, sharedref, <http://cbor.schmorp.de/value-sharing>)
		811	These tags are automatically decoded when encountered (and they do
		812	not result in a cyclic data structure, see "allow_cycles"),
		813	resulting in shared values in the decoded object. They are only
		814	encoded, however, when "allow_sharing" is enabled.
		815
		816	Not all shared values can be successfully decoded: values that
		817	reference themselves will currently decode as "undef" (this is not
		818	the same as a reference pointing to itself, which will be
		819	represented as a value that contains an indirect reference to itself
		820	- these will be decoded properly).
		821
		822	Note that considerably more shared value data structures can be
		823	decoded than will be encoded - currently, only values pointed to by
		824	references will be shared, others will not. While non-reference
		825	shared values can be generated in Perl with some effort, they were
		826	considered too unimportant to be supported in the encoder. The
		827	decoder, however, will decode these values as shared values.
		828
		829	256, 25 (stringref-namespace, stringref,
		830	<http://cbor.schmorp.de/stringref>)
		831	These tags are automatically decoded when encountered. They are only
		832	encoded, however, when "pack_strings" is enabled.
		833
		834	22098 (indirection, <http://cbor.schmorp.de/indirection>)
		835	This tag is automatically generated when a reference are encountered
		836	(with the exception of hash and array references). It is converted
		837	to a reference when decoding.
		838
		839	55799 (self-describe CBOR, RFC 7049)
		840	This value is not generated on encoding (unless explicitly requested
		841	by the user), and is simply ignored when decoding.
		842
		843	NON-ENFORCED TAGS
		844	These tags have default filters provided when decoding. Their handling
		845	can be overridden by changing the %CBOR::XS::FILTER entry for the tag,
		846	or by providing a custom "filter" callback when decoding.
		847
		848	When they result in decoding into a specific Perl class, the module
		849	usually provides a corresponding "TO_CBOR" method as well.
		850
		851	When any of these need to load additional modules that are not part of
		852	the perl core distribution (e.g. URI), it is (currently) up to the user
		853	to provide these modules. The decoding usually fails with an exception
		854	if the required module cannot be loaded.
		855
		856	0, 1 (date/time string, seconds since the epoch)
		857	These tags are decoded into Time::Piece objects. The corresponding
		858	"Time::Piece::TO_CBOR" method always encodes into tag 1 values
		859	currently.
		860
		861	The Time::Piece API is generally surprisingly bad, and fractional
		862	seconds are only accidentally kept intact, so watch out. On the plus
		863	side, the module comes with perl since 5.10, which has to count for
		864	something.
		865
		866	2, 3 (positive/negative bignum)
		867	These tags are decoded into Math::BigInt objects. The corresponding
		868	"Math::BigInt::TO_CBOR" method encodes "small" bigints into normal
		869	CBOR integers, and others into positive/negative CBOR bignums.
		870
		871	4, 5, 264, 265 (decimal fraction/bigfloat)
		872	Both decimal fractions and bigfloats are decoded into Math::BigFloat
		873	objects. The corresponding "Math::BigFloat::TO_CBOR" method always
		874	encodes into a decimal fraction (either tag 4 or 264).
		875
		876	NaN and infinities are not encoded properly, as they cannot be
		877	represented in CBOR.
		878
		879	See "BIGNUM SECURITY CONSIDERATIONS" for more info.
		880
		881	30 (rational numbers)
		882	These tags are decoded into Math::BigRat objects. The corresponding
		883	"Math::BigRat::TO_CBOR" method encodes rational numbers with
		884	denominator 1 via their numerator only, i.e., they become normal
		885	integers or "bignums".
		886
		887	See "BIGNUM SECURITY CONSIDERATIONS" for more info.
		888
		889	21, 22, 23 (expected later JSON conversion)
		890	CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore
		891	these tags.
		892
		893	32 (URI)
		894	These objects decode into URI objects. The corresponding
		895	"URI::TO_CBOR" method again results in a CBOR URI value.
453		896
454	CBOR and JSON	897	CBOR and JSON
455	CBOR is supposed to implement a superset of the JSON data model, and is,	898	CBOR is supposed to implement a superset of the JSON data model, and is,
456	with some coercion, able to represent all JSON texts (something that	899	with some coercion, able to represent all JSON texts (something that
457	other "binary JSON" formats such as BSON generally do not support).	900	other "binary JSON" formats such as BSON generally do not support).
…		…
463	interoperability is improved in the future, then the goal will be to	906	interoperability is improved in the future, then the goal will be to
464	ensure that decoded JSON data will round-trip encoding and decoding to	907	ensure that decoded JSON data will round-trip encoding and decoding to
465	CBOR intact.	908	CBOR intact.
466		909
467	SECURITY CONSIDERATIONS	910	SECURITY CONSIDERATIONS
468	When you are using CBOR in a protocol, talking to untrusted potentially	911	Tl;dr... if you want to decode or encode CBOR from untrusted sources,
469	hostile creatures requires relatively few measures.	912	you should start with a coder object created via "new_safe":
470		913
		914	my $coder = CBOR::XS->new_safe;
		915
		916	my $data = $coder->decode ($cbor_text);
		917	my $cbor = $coder->encode ($data);
		918
		919	Longer version: When you are using CBOR in a protocol, talking to
		920	untrusted potentially hostile creatures requires some thought:
		921
		922	Security of the CBOR decoder itself
471	First of all, your CBOR decoder should be secure, that is, should not	923	First and foremost, your CBOR decoder should be secure, that is,
472	have any buffer overflows. Obviously, this module should ensure that and	924	should not have any buffer overflows or similar bugs that could
		925	potentially be exploited. Obviously, this module should ensure that
473	I am trying hard on making that true, but you never know.	926	and I am trying hard on making that true, but you never know.
474		927
		928	CBOR::XS can invoke almost arbitrary callbacks during decoding
		929	CBOR::XS supports object serialisation - decoding CBOR can cause
		930	calls to any "THAW" method in any package that exists in your
		931	process (that is, CBOR::XS will not try to load modules, but any
		932	existing "THAW" method or function can be called, so they all have
		933	to be secure).
		934
		935	Less obviously, it will also invoke "TO_CBOR" and "FREEZE" methods -
		936	even if all your "THAW" methods are secure, encoding data structures
		937	from untrusted sources can invoke those and trigger bugs in those.
		938
		939	So, if you are not sure about the security of all the modules you
		940	have loaded (you shouldn't), you should disable this part using
		941	"forbid_objects".
		942
		943	CBOR can be extended with tags that call library code
		944	CBOR can be extended with tags, and "CBOR::XS" has a registry of
		945	conversion functions for many existing tags that can be extended via
		946	third-party modules (see the "filter" method).
		947
		948	If you don't trust these, you should configure the "safe" filter
		949	function, "CBOR::XS::safe_filter", which by default only includes
		950	conversion functions that are considered "safe" by the author (but
		951	again, they can be extended by third party modules).
		952
		953	Depending on your level of paranoia, you can use the "safe" filter:
		954
		955	$cbor->filter (\&CBOR::XS::safe_filter);
		956
		957	... your own filter...
		958
		959	$cbor->filter (sub { ... do your stuffs here ... });
		960
		961	... or even no filter at all, disabling all tag decoding:
		962
		963	$cbor->filter (sub { });
		964
		965	This is never a problem for encoding, as the tag mechanism only
		966	exists in CBOR texts.
		967
		968	Resource-starving attacks: object memory usage
475	Second, you need to avoid resource-starving attacks. That means you	969	You need to avoid resource-starving attacks. That means you should
476	should limit the size of CBOR data you accept, or make sure then when	970	limit the size of CBOR data you accept, or make sure then when your
477	your resources run out, that's just fine (e.g. by using a separate	971	resources run out, that's just fine (e.g. by using a separate
478	process that can crash safely). The size of a CBOR string in octets is	972	process that can crash safely). The size of a CBOR string in octets
479	usually a good indication of the size of the resources required to	973	is usually a good indication of the size of the resources required
480	decode it into a Perl structure. While CBOR::XS can check the size of	974	to decode it into a Perl structure. While CBOR::XS can check the
481	the CBOR text, it might be too late when you already have it in memory,	975	size of the CBOR text (using "max_size"), it might be too late when
482	so you might want to check the size before you accept the string.	976	you already have it in memory, so you might want to check the size
		977	before you accept the string.
483		978
		979	As for encoding, it is possible to construct data structures that
		980	are relatively small but result in large CBOR texts (for example by
		981	having an array full of references to the same big data structure,
		982	which will all be deep-cloned during encoding by default). This is
		983	rarely an actual issue (and the worst case is still just running out
		984	of memory), but you can reduce this risk by using "allow_sharing".
		985
		986	Resource-starving attacks: stack overflows
484	Third, CBOR::XS recurses using the C stack when decoding objects and	987	CBOR::XS recurses using the C stack when decoding objects and
485	arrays. The C stack is a limited resource: for instance, on my amd64	988	arrays. The C stack is a limited resource: for instance, on my amd64
486	machine with 8MB of stack size I can decode around 180k nested arrays	989	machine with 8MB of stack size I can decode around 180k nested
487	but only 14k nested CBOR objects (due to perl itself recursing deeply on	990	arrays but only 14k nested CBOR objects (due to perl itself
488	croak to free the temporary). If that is exceeded, the program crashes.	991	recursing deeply on croak to free the temporary). If that is
489	To be conservative, the default nesting limit is set to 512. If your	992	exceeded, the program crashes. To be conservative, the default
490	process has a smaller stack, you should adjust this setting accordingly	993	nesting limit is set to 512. If your process has a smaller stack,
491	with the "max_depth" method.	994	you should adjust this setting accordingly with the "max_depth"
		995	method.
492		996
		997	Resource-starving attacks: CPU en-/decoding complexity
		998	CBOR::XS will use the Math::BigInt, Math::BigFloat and Math::BigRat
		999	libraries to represent encode/decode bignums. These can be very slow
		1000	(as in, centuries of CPU time) and can even crash your program (and
		1001	are generally not very trustworthy). See the next section for
		1002	details.
		1003
		1004	Data breaches: leaking information in error messages
		1005	CBOR::XS might leak contents of your Perl data structures in its
		1006	error messages, so when you serialise sensitive information you
		1007	might want to make sure that exceptions thrown by CBOR::XS will not
		1008	end up in front of untrusted eyes.
		1009
		1010	Something else...
493	Something else could bomb you, too, that I forgot to think of. In that	1011	Something else could bomb you, too, that I forgot to think of. In
494	case, you get to keep the pieces. I am always open for hints, though...	1012	that case, you get to keep the pieces. I am always open for hints,
		1013	though...
495		1014
496	Also keep in mind that CBOR::XS might leak contents of your Perl data	1015	BIGNUM SECURITY CONSIDERATIONS
497	structures in its error messages, so when you serialise sensitive	1016	CBOR::XS provides a "TO_CBOR" method for both Math::BigInt and
498	information you might want to make sure that exceptions thrown by	1017	Math::BigFloat that tries to encode the number in the simplest possible
499	CBOR::XS will not end up in front of untrusted eyes.	1018	way, that is, either a CBOR integer, a CBOR bigint/decimal fraction (tag
		1019	4) or an arbitrary-exponent decimal fraction (tag 264). Rational numbers
		1020	(Math::BigRat, tag 30) can also contain bignums as members.
		1021
		1022	CBOR::XS will also understand base-2 bigfloat or arbitrary-exponent
		1023	bigfloats (tags 5 and 265), but it will never generate these on its own.
		1024
		1025	Using the built-in Math::BigInt::Calc support, encoding and decoding
		1026	decimal fractions is generally fast. Decoding bigints can be slow for
		1027	very big numbers (tens of thousands of digits, something that could
		1028	potentially be caught by limiting the size of CBOR texts), and decoding
		1029	bigfloats or arbitrary-exponent bigfloats can be extremely slow
		1030	(minutes, decades) for large exponents (roughly 40 bit and longer).
		1031
		1032	Additionally, Math::BigInt can take advantage of other bignum libraries,
		1033	such as Math::GMP, which cannot handle big floats with large exponents,
		1034	and might simply abort or crash your program, due to their code quality.
		1035
		1036	This can be a concern if you want to parse untrusted CBOR. If it is, you
		1037	might want to disable decoding of tag 2 (bigint) and 3 (negative bigint)
		1038	types. You should also disable types 5 and 265, as these can be slow
		1039	even without bigints.
		1040
		1041	Disabling bigints will also partially or fully disable types that rely
		1042	on them, e.g. rational numbers that use bignums.
500		1043
501	CBOR IMPLEMENTATION NOTES	1044	CBOR IMPLEMENTATION NOTES
502	This section contains some random implementation notes. They do not	1045	This section contains some random implementation notes. They do not
503	describe guaranteed behaviour, but merely behaviour as-is implemented	1046	describe guaranteed behaviour, but merely behaviour as-is implemented
504	right now.	1047	right now.
…		…
512	Only the double data type is supported for NV data types - when Perl	1055	Only the double data type is supported for NV data types - when Perl
513	uses long double to represent floating point values, they might not be	1056	uses long double to represent floating point values, they might not be
514	encoded properly. Half precision types are accepted, but not encoded.	1057	encoded properly. Half precision types are accepted, but not encoded.
515		1058
516	Strict mode and canonical mode are not implemented.	1059	Strict mode and canonical mode are not implemented.
		1060
		1061	LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
		1062	On perls that were built without 64 bit integer support (these are rare
		1063	nowadays, even on 32 bit architectures, as all major Perl distributions
		1064	are built with 64 bit integer support), support for any kind of 64 bit
		1065	integer in CBOR is very limited - most likely, these 64 bit values will
		1066	be truncated, corrupted, or otherwise not decoded correctly. This also
		1067	includes string, array and map sizes that are stored as 64 bit integers.
517		1068
518	THREADS	1069	THREADS
519	This module is not guaranteed to be thread safe and there are no plans	1070	This module is not guaranteed to be thread safe and there are no plans
520	to change this until Perl gets thread support (as opposed to the	1071	to change this until Perl gets thread support (as opposed to the
521	horribly slow so-called "threads" which are simply slow and bloated	1072	horribly slow so-called "threads" which are simply slow and bloated

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing CBOR-XS/README (file contents): Revision 1.8 by root, Tue Oct 29 22:04:52 2013 UTC vs. Revision 1.18 by root, Wed Dec 7 14:14:30 2016 UTC

Diff Legend

Comparing CBOR-XS/README (file contents):
Revision 1.8 by root, Tue Oct 29 22:04:52 2013 UTC vs.
Revision 1.18 by root, Wed Dec 7 14:14:30 2016 UTC