summaryrefslogtreecommitdiff
path: root/tanja.pod
blob: 37e67873a4c6207d7ca552b9ac4e0fe0eed378cf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
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>