summaryrefslogtreecommitdiff
path: root/spec.pod
blob: 5a912130e79a6f4adb69bd531a8cbb5d58e2643b (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

=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?