summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorYorhel <git@yorhel.nl>2012-02-15 13:33:53 +0100
committerYorhel <git@yorhel.nl>2012-02-15 13:33:53 +0100
commitd87a1b1caddb48336c92e4ff1cc94f4fd65d8acd (patch)
treeca729e13f30a1eb20c47d21ddf50bb26656dadf9
parent9880043a97fdebbf2c0d948e9f1209960c248db9 (diff)
Added doc/tanja.pod + Rewrote parts of proto.go (still unfinished)
-rw-r--r--proto.pod4
-rw-r--r--tanja.pod138
2 files changed, 142 insertions, 0 deletions
diff --git a/proto.pod b/proto.pod
index 97df5b8..09c3205 100644
--- a/proto.pod
+++ b/proto.pod
@@ -70,6 +70,10 @@ the REGISTER command.
Indicates that the sender of the message is not interested anymore in receiving
tuples matching the pattern that has previously been registered with REGISTER.
+An UNREGISTER message with a $pid not known to the receiver (e.g. it has
+already been UNREGISTER'ed or has never been REGISTER'ed previously) should be
+ignored.
+
=item TUPLE $tid $tuple
Passes a tuple from the sending side to the receiving side. Every tuple is only
diff --git a/tanja.pod b/tanja.pod
new file mode 100644
index 0000000..37e6787
--- /dev/null
+++ b/tanja.pod
@@ -0,0 +1,138 @@
+TODO: What about allowing wildcards in Tuples?
+TODO: Allow binary strings in tuples?
+TODO: Allow the value NULL/nil in tuples?
+TODO: More ordering constraints on message receival?
+
+
+=head1 Semantics
+
+=head2 Tuples and patterns
+
+A I<tuple> is an ordered set (or simply: an array) of zero or more elements.
+Each element may be of a different type. Allowed types are:
+
+=over
+
+=item * Integers
+
+=item * Floating point numbers
+
+=item * Strings
+
+=item * Booleans
+
+=item * Arrays with elements of allowed types
+
+=item * Mapping between strings and allowed types
+
+This includes hash tables and structs. The order of the key/value pairs should
+not matter. The values in a map do not necessarily have to be of the same type.
+
+=back
+
+A I<pattern> is similar to a tuple, but has a smaller set of allowed types:
+
+=over
+
+=item * Integers
+
+=item * Strings
+
+=item * Booleans
+
+=item * Wildcards
+
+=back
+
+That is: Floating point numbers, arrays and maps are not allowed in patterns,
+but patterns do have a special I<wildcard> value.
+
+All integers should be representable in either a signed (two's complement) or
+unsigned 64bit integer. Thus anything in the range of C<-2^63> to C<2^64-1>
+(both inclusive) are valid integer values.
+
+The maximum precision of floating point numbers is dictated by the
+implementation. In practice, this can be expected to be either single precision
+or double precision IEEE 754 floating points.
+
+Strings should be encoded in UTF-8.
+
+=head2 Matching
+
+Tuples are I<matched> using patterns. This is much like pattern matching in the
+text processing world: a tuple represents some input string and a pattern is
+similar to a (somewhat less powerful) regular expression or C<fnmatch(3)>-style
+pattern.
+
+A tuple is said to I<match> a pattern when, for each element in the pattern,
+the tuple has a matching element at the same location. Two elements match if
+either of the following holds:
+
+=over
+
+=item 1. The element in the pattern is a wildcard
+
+=item 2. The elements are of the same type, and their value is equivalent.
+
+=back
+
+The first rule is trivial: if the element of the pattern is a wildcard, then
+the corresponding element in the tuple can be of any type and value. The second
+rule is slightly less obvious, and requires the type definitions given in the
+previous section to be interpreted properly. One implication of the second rule
+is that it is impossible to do a non-wildcard match on anything other than
+integers, strings and booleans, since values of other types are not allowed in
+patterns. Another thing to keep in mind is that both values have to be of the
+same type, so the integer C<0> is not equivalent to the boolean C<false>. Nor
+is the string C<"15"> equivalent to the integer C<15>. However, integers are
+always equal if their numeric value is equivalent (provided they are within the
+specified range). This means that if, within an implementation, a tuple with an
+element of type uint8 with value C<5> is matched against a pattern with an
+element at the same location of type int64 and with the same value, then these
+elements match. Two strings are equal if they are of the same length and all of
+their characters have the same unicode values. Strings are thus matched in a
+case-sensitive fashion. The above rules also imply that the tuple must hold at
+least as many elements as the pattern.
+
+
+
+
+=head1 Communication primitives
+
+There are a total of four communication primitives: I<register> and I<response>
+for receiving messages and I<send> and I<request> to send messages. The term
+I<message> is a synonym for I<tuple> in this context - all communication is
+performed with tuples.
+
+I<TODO: describe what a "session" is.>
+
+=head2 Send / register
+
+Send and register are the two simplest form of communication. A session uses
+the I<register> primitive to indicate that it is interested in receiving tuples
+that match a certain pattern. A session can register as many patterns as it
+wishes. If an incoming tuple matches multiple patterns registered by the same
+session, the tuple will be received multiple times. (But note that
+implementations may optimize away duplicate tuples for more efficient
+transmission - the behaviour of duplication can still be achieved when a list
+of registered patterns is kept locally).
+
+The I<send> primitive is used to "send" a tuple to other sessions. It will be
+received by any session that has registered for a matching pattern. This
+primitive does not tell the sending session whether there were any recipients,
+and it is not an error to send out tuples when no other sessions have
+registered for it. Outgoing tuples are also matched against the patterns that
+the sending session has registered for, so if a session sends out a tuple
+matching one of its own pattern, then the tuple will be sent back as well.
+(Again, these are purely semantics, an implementation can achieve this
+behaviour without needing to communicate with any other session.)
+
+Messages are always received by a session in the same order as the sending
+session sent them. Besides that, there are no ordering restrictions: Messages
+sent by two different sessions may be received by an other session in any
+order.
+
+
+=head2 Request / response
+
+I<TODO>