view release on metacpan or  search on metacpan

lib/Data/FastPack.pod  view on Meta::CPAN

C<id> is is the channel id within the file/stream. It relates to a definition
file. 0 indicates a meta data point which is JSON or other structured data,
which alters the processing of the file. 

Optionally a namespace can be used to provide dynamic ID generation. The ids
are mapped from a name/label/topic/ to an integer. Additional mapping messages
are inserted into the stream to facilitate this mapping at both ends.

C<len> is the length of the payload. If the length is larger than 2^32 then it
must be fragmented at the 'application level'.


C<payload> is the data.

C<padding> Every record is padded to an 8 byte bounadary, with nulls, if nessicary

=head1 API Usage

=head2 Encoding and Decoding

=head3 encode_fastpack

  encode_fastpack $buf, $inputs, $limit, $namespace


Encodes and array ref of an array refs C<[time, ID, payload]> in to the buffer
C<$buf>.  C<$buf> is aliased internally, and not copied. All need encoded
messages are appended to the buffer.

If C<limit> is supplied, and less then the length of the C<$input>
array, only this number of inputs will be consumed.  Inputs consumed are
spliced out of the input array to allow the same array to be appended to
externally

If C<$namespace> is provided, all messages are encoded assuming the id is name
and dynamically allocates an ID to the name space.  Note C<$limit> must be
provided  (even if undefended) to use this argument.

Namespace if prevented from using C<0>, C<"0">, or C<undef> as names. Messages
with these names issue a warning.

If a C<$namespace> is utilised, the ID/name  of the message can be any string.
It is mapped to an integer code. If the message is the first one to use the
ID, an extra message mapping the integer to the name (id becomes the integer
value, payload becomes the name), in inserted into the output. 

If the message has and ID of "0", and a payload with no length, this resets the
mappings in the namespace and is output as normal


=head3 decode_fastpack

  decode_fastpack $buf,$output, $limit, $namespace


Decodes FastPack messages from C<$buf>, consuming it as it progresses. C<$buf>
is aliases so new messages can be added to it externally.

C<$output> is a reference to an array to store the decoded messages. The
messages are decoded into  C<[time, id, payload]>.

If C<$limit> is provided, this is the maximum number of messages to decode
during a single call. If not provided or undef, 4096 is the default.


C<$namespace> if provided, int  enables named ids. Decoded messages have the id
mapped to a name stored in the names space. If its the id has not been
encountered before, it uses the payload as the name to update the internal
mapping. This message is not sent to the output, as it is intended to update
the mapping only.

If the message has and ID of "0", and a payload with no length, this resets the
mappings in the namespace and is not forward past the decoder

=head2 Namspaces

=head3 create_namespace

  create_namespace

Returns a name space structure for named ids. Separate name spaces structure
are needed for encoding and decoding ends, even withing the same program.


=head3 id_for_name

  id_for_name $namespace, $name

Returns the integer id in C<$namespace> for  C<$name>. Useful for testing and
optimisation when multiple of the same messages are being encoded.

=head3 name_for_id

  name_for_id $namespace, $id

Returns the name id in C<$namespace> for  C<$id>. Useful for testing and
optimisation when multiple of the same messages are being encoded.

=head1 AUTHOR

Ruben Westerberg, E<lt>drclaw@mac.comE<gt>

=head1 REPOSITORTY and BUGS

Please report any bugs via git hub: L<https://github.com/drclaw1394/perl-data-fastpack>


=head1 COPYRIGHT AND LICENSE

Copyright (C) 2025 by Ruben Westerberg

Licensed under MIT

=head1 DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE.