Author: Tony Rogvall <tony(at)rogvall(dot)se>
    Status: Draft
    Type: Standards Track
    Created: 31-Aug-2010
    Erlang-Version: OTP_R14B
    Post-History:
****
EEP 34: Extended basic packet options for decode_packet
----

Abstract
========

This EEP describes new basic packet options that is used by the
`gen_tcp` which are also present, and the same, as in the
`erlang:decode_packet`.

Rationale
=========

Current packet options used in `erlang:decode_packet` cover a range of
packet types.  The basic ones are `{packet,0}`, `{packet,1}`,
`{packet,2}`, and `{packet,4}`.  On outbound traffic from `gen_tcp`
these options prefix the packets with `N` extra bytes containing an
integer in big endian format containing the size of the data.

When communicating with end points implemented by other party it is
not always possible to suggest that packet length is present in
big endian format or that it is 4 bytes.  Today with 64-bit machine
showing up it may even be possible that we soon find protocols sending
plain machine dependent 64-bit words as packet length descriptors.

New packet types
================

This EEP suggest to extend the packet bytes to the range 0-8.  Note
that the internal maximum packet size is not affected by this EEP,
only the format of the packet size indicator.

Furthermore a negative range is suggested to signal little endian
formatted size indicator in range -1 .. -8.  `{packet,-1}` is
equivalent with `{packet,1}`.  The number of packets bytes prefixed is
thus `abs(PBytes)` where `PBytes` is in range -8 .. 8.

This EEP also suggest a fixed size packet mode, expressed as `{packet,
{size,N}}`.  This mode acts much like `{packet,0}` in regards to
packet bytes, no packet bytes are used.  The difference is that, in
`{active,true}` or `{active,once}` mode, while `{packet,0}` collects
any data available, the `{packet,{size,N}}` mode collects exactly `N`
bytes before passing it on to the "owner" process.  Suggested
implementation minimum limitations for `N` is unsigned 16-bit,
resulting in a minimum size of 1 and and maximum size of 65535.  A
packet size of less than 1 should always result in a badarg error.

Summary
=======

The packet types suggest by this EEP are:

- `{packet,P}`  
  for integer `P` in range -8 .. 8.  This is an extension to the
  existing integer packet types.

- `{packet,{size,N}}`  
  `N` is in range > 0 and the maximum `N` is implementation
  dependent but never less then 65535.

Backward compatibility
=====================

The author of this EEP has implemented this proposal in the
Erlang/OTP standard git release, and has not found any backwards
compatibility problems.  The files affected by this proposal
implementation are: `inet_drv.c`, `packet_parser.c`, `packet_parser.h`
and `erl_bif_port.c`.

Copyright
=========

This document has been placed in the public domain.

[EmacsVar]: <> "Local Variables:"
[EmacsVar]: <> "mode: indented-text"
[EmacsVar]: <> "indent-tabs-mode: nil"
[EmacsVar]: <> "sentence-end-double-space: t"
[EmacsVar]: <> "fill-column: 70"
[EmacsVar]: <> "coding: utf-8"
[EmacsVar]: <> "End:"