diff options
-rw-r--r-- | proto.pod | 4 | ||||
-rw-r--r-- | tanja.pod | 138 |
2 files changed, 142 insertions, 0 deletions
@@ -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> |