view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    "time" is the absolute time of the sample or the difference in time from
    the current message to the previous message in the same stream. The
    exact meaning of the time is as per the definition messages. It is a
    double float to allow web browsers to utilise high resolution time, as
    they do not support 64bit integers.

    "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.

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

    "payload" is the data.

    "padding" Every record is padded to an 8 byte bounadary, with nulls, if
    nessicary

API Usage
  Encoding and Decoding
   encode_fastpack
      encode_fastpack $buf, $inputs, $limit, $namespace

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

    If "limit" is supplied, and less then the length of the $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 $namespace is provided, all messages are encoded assuming the id is
    name and dynamically allocates an ID to the name space. Note $limit must
    be provided (even if undefended) to use this argument.

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

    If a $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

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

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

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

    If $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.

    $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

  Namspaces
   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.

   id_for_name
      id_for_name $namespace, $name

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

   name_for_id
      name_for_id $namespace, $id

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

AUTHOR
    Ruben Westerberg, <drclaw@mac.com>

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

COPYRIGHT AND LICENSE
    Copyright (C) 2025 by Ruben Westerberg

    Licensed under MIT

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.