Add EEP 34

eeps/eep-0034.md

@@ -0,0 +1,101 @@
+    Author: Tony Rogvall <tony(at)rogvall(dot)se>
+    Status: Draft
+    Type: Standards Track
+    Created: 31-Aug-2010
+    Erlang-Version: R14B
+    Post-History:
+****
+EEP 34: Extended basic packet options for decode_packet
+----
+
+
+Abstract
+========
+
+This EEP decribes 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 containg 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 machin 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.
+
+Further more a negative range is suggested to signal little endian
+formated size indicator in range -1 .. -8.  The `{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}` collectes
+any data available, the `{packet,{size,N}}` mode collects exacly `N`
+bytes before passing it on to the "owner" process.  Suggested
+implementation minium limitiations for `N` is unsigned 16-bit,
+resulting in a minium size of 1 and and maximum size of 65535.  A
+packet size of less than 1 should always result in 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 
+    dependant but never less then 65535.
+
+
+
+Backward compatiblity
+=====================
+
+The author of this EEP have implemented this proposal in the
+Erlang/OTP standard git release, and has not found any backwards
+compatiblity 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:"