summaryrefslogtreecommitdiff
path: root/spec.pod
diff options
context:
space:
mode:
authorYorhel <git@yorhel.nl>2012-02-19 11:21:32 +0100
committerYorhel <git@yorhel.nl>2012-02-19 11:21:32 +0100
commitc2fdfcda3aaf04dfcbc9e09fb0eb501863b902f0 (patch)
treea3f03924a5624e2452834d97df53e5908020cd4a /spec.pod
parentd2b68a79e101054f2649d9273c30f193ccb2c82b (diff)
doc: tanja.pod -> spec.pod + specify that wildcars are allowed in tuples
Diffstat (limited to 'spec.pod')
-rw-r--r--spec.pod135
1 files changed, 135 insertions, 0 deletions
diff --git a/spec.pod b/spec.pod
new file mode 100644
index 0000000..5a91213
--- /dev/null
+++ b/spec.pod
@@ -0,0 +1,135 @@
+
+=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
+
+I<TODO:> Get rid of booleans and stick with integers instead?
+
+=item * Arrays with elements of allowed types
+
+The elements of the array do not have to be of the same type. A tuple itself is
+therefore also an array.
+
+=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.
+
+=item * Wildcards
+
+=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.
+
+All integers should be representable in a signed (two's complement) 64-bit
+integer. Thus anything in the range of C<-2^63> to C<2^63-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. Either element 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 either the pattern or the tuple is
+a wildcard, then other element 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.
+
+I<TODO:> Allow integer-formatted strings to do match integers of the same value?
+
+I<TODO:> Allow the integer C<10> in a pattern to match a float C<10.0> in a tuple?
+
+
+
+=head1 Communication
+
+I<TODO:> Describe the terms "network" and "session"
+
+I<TODO:> Refactor with the return-path being an argument of I<send>.
+
+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.
+
+I<TODO:> More ordering constraints on message receival?