mission statement

svn path=/trunk/externals/iem/iemnet/; revision=13268

1 files changed, 62 insertions, 0 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..3c73451
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,62 @@
+iemnet - networking for Pd
+==========================
+
+this is a fork of martin peach's "net" library, that allows low-level
+interaction with networks on OSI-layer 5 (transport layer)
+
+Why fork?
+=========
+
+the original library is still actively maintained by martin peach.
+however:
+- forking allows me to experiment with new features/techniques more easily
+- forking allows to remove all the legacy cruft (and not care about
+  compatibility now)
+- the development mode in the original library would involve the upstream author
+  "signing-off" any changes (debatable; but i don't want to submit experimental
+  code to their stable code base)
+
+in practice one of the major drawbacks i see in upstream is, that (in the
+multithreaded objects), for each message a separate thread is spawned. this
+leads to excessive use of system ressources (detaching and joining threads takes
+time), easy DoS (each thread uses one in a limited number of thread handles),
+and abandons determinism (nobody guarantees that parallel threads are executed
+"in order"; thus a message in a later-spawned thread might be delivered to the
+socket earlier than older messages - effectively circumventing one of the
+promises of TCP/IP: that all packets will reappear in order; i haven't seen this
+behaviour of mrpeach/net in real life yet; however i don't see any
+countermeasurements either)
+
+on the long run compatibility with the upstream library is intended.
+(though probably not for all the cruft that is in there)
+
+
+Design:
+=======
+
+easy to maintain:
+re-used code is bundled in a small "library" (currently only a single file
+ienet.c), which is linked statically against the externals.
+this library handles all the send/receive stuff (whether it uses threads or not
+and if so how, is an implementation detail)
+the lib doesn't know anything about the actual transport protocol. it only
+interacts with a socket.
+
+easy to use:
+
+
+
+
+
+Authors:
+========
+currently iemnet is developed by IOhannes m zmölnig
+
+it (being a fork) is heavily based on code written by Martin Peach, who again
+has used code by Olaf Matthes and Miller Puckette
+
+
+LICENSE:
+========
+iemnet is published under the GPL.
+see LICENSE.txt for more information