BIND 10 trac2738, updated. 7b3ab876a7fb697245c81d03bd477f81136355e8 [2738] Describe behavior of clients
BIND 10 source code commits
bind10-changes at lists.isc.org
Thu Apr 25 13:10:53 UTC 2013
The branch, trac2738 has been updated
via 7b3ab876a7fb697245c81d03bd477f81136355e8 (commit)
via 4963031b007d9e9f15cacfd058edc20a6d33bf37 (commit)
via b4e44a1c5f4f1fa5c16af5bcb2a3ed48a29c1da6 (commit)
via 73feee77d8a05f458c90990c8ff95f3338c54d72 (commit)
from 430bc7504e0b6d439440376bc6b1c56fc69280f7 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 7b3ab876a7fb697245c81d03bd477f81136355e8
Author: Michal 'vorner' Vaner <michal.vaner at nic.cz>
Date: Thu Apr 25 15:07:35 2013 +0200
[2738] Describe behavior of clients
commit 4963031b007d9e9f15cacfd058edc20a6d33bf37
Author: Michal 'vorner' Vaner <michal.vaner at nic.cz>
Date: Thu Apr 25 14:06:47 2013 +0200
[2738] Some wording & clarifications
commit b4e44a1c5f4f1fa5c16af5bcb2a3ed48a29c1da6
Author: Michal 'vorner' Vaner <michal.vaner at nic.cz>
Date: Thu Apr 25 13:37:02 2013 +0200
[2738] Clarify blocking & fast operations
commit 73feee77d8a05f458c90990c8ff95f3338c54d72
Author: Michal 'vorner' Vaner <michal.vaner at nic.cz>
Date: Thu Apr 25 13:32:39 2013 +0200
[2738] Remove ipc-high-2
It was mostly an example and is now merged to the base version. No
longer needed.
-----------------------------------------------------------------------
Summary of changes:
doc/design/ipc-high-2.txt | 225 ---------------------------------------------
doc/design/ipc-high.txt | 80 ++++++++++++----
2 files changed, 61 insertions(+), 244 deletions(-)
delete mode 100644 doc/design/ipc-high-2.txt
-----------------------------------------------------------------------
diff --git a/doc/design/ipc-high-2.txt b/doc/design/ipc-high-2.txt
deleted file mode 100644
index 6c34554..0000000
--- a/doc/design/ipc-high-2.txt
+++ /dev/null
@@ -1,225 +0,0 @@
-The communication system consists of
- - the "bus" (or "msgq" (as a concept name; not necessarily mean a
- daemon process), or whatever). below we simply call it "(the)
- system".
- - users: a user of the system, which would mean some application
- process in practice, but in this high level design it's a
- conceptual entity.
- - sessions: a session is an interface for a user of the
- system, through which the user can communicate with other users or
- with the system itself. A single user can have multiple
- sessions (but a session only belongs to one user).
- - messages: a message is a data blob to be exchanged between users
- or between a user and the system. each message has the
- destination, which is either: the system, a specific session, or a
- group of sessions. some types of messages expect a response, and
- some others are expected to be one-way. a message sent to a group
- must always be one-way.
- - groups: a named set of sessions. a message can be destined to a
- specific group, in which case the same copy of the message will be
- delivered to these sessions.
-
-'''Session Interface'''
-
-The session interface is a conceptual programming interface for a user
-of the system. It encapsulates one single session to the system, and
-provides methods of sending and receiving messages through the session
-(in practice of our implementation, this basically means the `Session`
-class interface).
-
-- Session establishment: any operation on the session interface begins
- with session establishment. It must succeeds and is considered a
- non blocking operation. If there's any error the user must consider
- it fatal and terminate.
-
-- Send operation: a user can send a message over the session. This
- interface ensures it always succeeds and is non blocking (note:
- internally, this could be just based on a (naive) assumption, via
- internal buffering, or whatever). If any error is reported the user
- must consider it fatal and terminate. If the message expects a
- response, a unique ID is given for identifying the response.
-
-- Synchronous read operation: a user can receive a message from the
- system or other user (or possibly even itself). The message could
- be either a response to a specific message (called a "request") it
- has sent before, or any new incoming message (maybe a request from
- other user or one-way message). In the former case, the user
- specifies the ID of the request message. If this is a response from
- the system, it must succeed and can (effectively) be considered non
- blocking; in all other cases it can block. This operation can fail
- due to "timeout", which means either the receiver of the request is
- not compliant and didn't respond, or it's extremely busy and non
- responsive, or simply isn't running. If any other error is
- reported, including a timeout for a response from the system, the
- user must consider it fatal and terminate.
-
-- Asynchronous read operation: the session interface should also
- support asynchronous read operation, where the user registers an
- interest on any new incoming message or a response to a specific
- request message with a callback. The registration itself must
- always succeed and is non blocking. When the request message is
- delivered, the interface triggers the registered callback. It could
- also mean a timeout or any other error (but any other errors must
- be considered fatal as the synchronous case).
-
-- Group membership management: this interface supports the concept of
- session "groups". a group consists of a set of sessions (called
- "subscribers") that are interested in receiving messages destined to
- that group. the following operations are available to manage the
- subscription:
- - subscription operation: a user can indicate an interest on
- receiving messages for the group on the session. this would
- actually be realized via a message exchange with the system,
- and it must succeed and be non block.
- - unsubscription operation: a user that has subscribed to a group
- can indicate it's no longer interested in subscribing to the
- group. this would actually be realized via a message exchange
- with the system, and it must succeed and be non block.
- - watch operation: a user can indicate an interest on a list of
- current subscribers of a given group. a watch operation would
- actually be realized via a message exchange with the system,
- and it must succeed and be non block. it will request a response,
- and the response contains the list of subscriber sessions. the
- system periodically sends a message whenever there's a change in
- the group subscribers.
- - unwatch operation: a user that has watched a group can indicate
- it's no longer interested in watching the group. this would
- actually be realized via a message exchange with the system, and
- it must succeed and be non block. the system will stop sending
- the periodic message of changes to the group on receiving this
- message.
-
-- Group communication: there are two ways for a user to communicate
- with sessions of a group:
- - sending a message to a group: a user can send a message to the
- sessions of a group as a single operation. this interface and the
- system ensures the message is delivered to all the sessions
- subscribing (see the "Reliability" bullet below), but the user
- cannot get a response from the destination sessions. in fact,
- there's technically quite difficult, if not impossible, to
- effectively get responses in this case, and it will make corner
- cases such as a subset of the sessions is non responsive trickier.
- - get a list of subscribers of the group using the "watch"
- operation, and send the same message to each of the subscriber
- sessions. In this case the user can request a response, and make
- a higher level decision on corner cases for the convenience of the
- user. in general, this way of communication is preferred unless
- the user doesn't have to care who actually receives the message
- (e.g., when the message is purely informational and could even be
- lost).
-
-- Reliability: this interface, with the help of the system, ensures
- message delivery is reliable. When a user sends messages from
- session A to session B (or to the system), all of the messages will
- be delivered in the sent order without any modification, as long as
- the destination session (B) exists.
-
-'''Additional/supplemental concepts'''
-- session: a session is established by the owner user with the
- system. it's given a unique (and never reused) ID (throughout the
- entire system) by the system at the time of establishment.
- This ID is called "lname" (but we might revisit this naming at this
- opportunity - no one knows what 'l' means and it could cause
- unnecessary confusion).
-
-- group: a "group" consists of a set of "subscriber" sessions and a
- set of "watcher" sessions. at least one of the two sets must be non
- empty, but one of them can be empty. A group is given a name that
- is unique throughout the system by the users of these sessions.
- Implementations of users are assumed to have consistent naming
- policy of the groups.
-
-- message: a blob of data exchanged between users or between a user
- and the system. messages are categorized by their "types". Known
- types include: "SEND" used for message exchanges between users;
- "GET LNAME" used between a user and the system so the user gets
- the ID (lname) of a session; "SUBSCRIBE" used between a user and
- the system so the user tells the system it wants to subscribe to a
- group. Each message also has a "need response" flag. If it's on,
- the sender needs a response to the message. In that case the
- message contains a unique sequence ID by the sender (unique per the
- session through which the message is sent). that sequence ID should
- be copied in to the corresponding response. If the "need response"
- flag is off, the receiver of the message shouldn't respond to it; if
- it does, that response should be ignored by the original sender.
-
-- message destination: each message of type "SEND" is associated with
- its intended destination. its either a group name or a session ID
- (lname). If it's a group name, the message is intended to be
- delivered to its all subscriber sessions. If it's a session ID,
- it's intended to be delivered to that specific session. The
- destination of a response cannot be a group.
-
-'''System behavior'''
-
-The following may be too detailed for the purpose of the high level
-design doc. But hopefully it helps understand it more concretely,
-and, in any event, we'll need this level of specification too.
-
-== Session Management ==
-- the system maintains a list of active sessions established by users
- with their lnames.
-- when a user establishes a session with the system, the system
- gives a unique ID ("lname") to the session, and adds the pair of the
- ID and session to the list.
-- if the system receives a "GET LNAME" message that asks the ID of the
- session through which the message is delivered, it returns a response
- containing the requested lname in the data.
-- when a user explicitly closes (one of) its session(s), the system
- immediately knows the corresponding session is now unusable and
- updates the list accordingly.
-- when a user terminates, the system immediately knows any unclosed
- sessions to the user are now unusable and updates the list
- accordingly.
-
-== Group Management ==
-- the system maintains a list of active groups.
-- if the system receives a "SUBSCRIBE" type message for a group, it
- adds the receiving session as a subscriber session of the group in
- the list. If the group did not exist in the list, it creates a new
- one. It also sends a "NEW SUBSCRIBER" (or something) message,
- containing the newly added session lname, to each of the current
- watchers of the group.
-- if the system receives a "WATCH" type message for a group, it
- adds the receiving session as a watcher session of the group in
- the list. If the group did not exist in the list, it creates a new
- one. This message must have a "need response" flag on, and the
- system sends a response containing a list of the current subscribers.
-- if the system receives an "UNSUBSCRIBE" type message for a group, it
- removes the receiving session as a subscriber session of the group
- from the list. If both subscribers and watchers for the group become
- empty, it removes the group from the list. It also sends a "LEAVING
- SUBSCRIBER" (or something) message, containing the lname of the
- leaving session, to each of the watchers of the group.
-- if the system receives a "UNWATCH" type message for a group, it
- removes the receiving session as a watcher session of the group
- from the list. If both subscribers and watchers for the group become
- empty, it removes the group from the list. this message should not
- have a response flag on.
-- when a user explicitly closes (one of) its session(s), the system
- goes through the group list. For each group that has the closing
- session as a subscriber, it handles the session as if it receives an
- "UNSUBSCRIBE" message over that session for that group. Likewise,
- for each group that has the closing session as a watcher, it handles
- the session as if it receives an "UNWATCH" message over that session
- for that group.
-- when a user terminates, the system identifies any unclosed
- sessions to the user, and performs the action of the previous
- bullet for each of these sessions.
-
-== Message Routing ==
-- if the system receives a "SEND" message from a session destined to
- another session (specified as its lname), it identifies the
- corresponding destination session and delivers the message to it.
-- if the system receives a "SEND" message from a session destined to
- a session group, it identifies the subscriber sessions of the group,
- and delivers the message to each of these sessions.
-
-'''User behavior'''
-- A user must have at least one session with the system. It can
- have multiple sessions.
-- For each established session, the user must first send the "GET
- LNAME" type of message and wait for a response. For any subsequent
- messages sent from that session should have the given lname to
- indicate the sender.
-- ... and so on
diff --git a/doc/design/ipc-high.txt b/doc/design/ipc-high.txt
index d3e22e1..08c73c2 100644
--- a/doc/design/ipc-high.txt
+++ b/doc/design/ipc-high.txt
@@ -20,17 +20,18 @@ session::
single user.
message::
A data blob sent by one user. The recipient might be the system
- itself, other user or set of users (possibly empty). Message is
- either a response or an original message (TODO: Better name?).
+ itself, other session or set of sessions (called group, see below,
+ it is possibly empty). Message is either a response or an original
+ message (TODO: Better name?).
group::
A named set of sessions. Conceptually, all the possible groups
exist, there's no explicit creation and deletion of groups.
session id::
Unique identifier of a session. It is not reused for the whole
lifetime of the system. Historically called `lname` in the code.
-undelivery notification::
+undelivery signal::
While sending an original message, a client may request an
- undelivery notification. If the recipient specification yields no
+ undelivery signal. If the recipient specification yields no
sessions to deliver the message to, the system informs user about
the situation.
sequence number::
@@ -40,6 +41,15 @@ sequence number::
sequence number had the message it response to. Even responses and
messages not expecting answer have their sequence number, but it is
generally unused.
+non-blocking operation::
+ Operation that will complete without waiting for anything.
+fast operation::
+ Operation that may wait for other process, but only for a very short
+ time. Generally, this includes communication between the user and
+ system, but not between two clients. It can be expected to be fast
+ enough to use this inside an interactive session, but may be too
+ heavy in the middle of query processing, for example. Every
+ non-blocking operation is considered fast.
The session
-----------
@@ -51,8 +61,7 @@ Possible operations include:
Opening a session::
The session is created and connects to the system. This operation is
- fast, but it can still block for short amount of time. The session
- receives session id from the system.
+ fast. The session receives session id from the system.
Group management::
A user may subscribe (become member) of a group, or unsubscribe from
@@ -60,9 +69,9 @@ Group management::
Send::
A user may send a message, addressed to the system, or other
- client(s). This operation is generally expected to be non-blocking
- (but it may be based on the assumption of OS buffering and the
- system not being overloaded).
+ session(s). This operation is expected to be non-blocking
+ (current implementation is based on assumption of how OS handles the
+ sends, which may need to be revisited if it turns out to be false).
Receive synchronously::
User may wait for an incoming message in blocking mode. It is
@@ -77,7 +86,8 @@ Receive asynchronously::
Terminate::
A session may be terminated. No more messages are sent or received
over it, the session is automatically unsubscribed from all the
- groups. A session is terminated automatically if the user exits.
+ groups. This operation is non-blocking. A session is terminated
+ automatically if the user exits.
Assumptions
-----------
@@ -139,7 +149,8 @@ Notifications about group subscriptions::
When a session subscribes to a group or unsubscribes from a group, a
notification is sent to interested users. The notification contains
both the session ID of the session subscribing/unsubscribing and
- name of the group.
+ name of the group. This includes notifications about aliases (since
+ aliases are groups internally).
Commands to list sessions::
There's a command to list session IDs of all currently opened sessions
and a command to list session IDs of all sessions subscribed to a
@@ -147,8 +158,15 @@ Commands to list sessions::
the information might be outdated at the time it is delivered to the
user.
-Note that in early stages of startup (before the configuration
-manager's session is opened), the `Msgq` alias is not yet available.
+User shows interest in notifications about sessions and group
+subscriptions by subscribing to a group with well-known name (as with
+any notification).
+
+Note that due to implementation details, the `Msgq` alias is not yet
+available during early stage of the bootstrap of bind10 system. This
+means some very core services can't rely on the above services of the
+system. The alias is guaranteed to be working before the first
+non-core module is started.
Higher-level services
---------------------
@@ -159,7 +177,7 @@ are of three general types:
Command::
A message sent to single destination, with the undeliverable
- notifications turned on and expecting an answer. This is a request
+ signal turned on and expecting an answer. This is a request
to perform some operation on the recipient (it can have side effects
or not). The command is identified by a name and it can have
parameters. A command with the same name may behave differently (or
@@ -171,7 +189,7 @@ Reply::
command was run successfully and contains an optional result, or
notifies the sender of failure to run the command. Success and
failure differ only in the payload sent through the system, not in
- the way it is sent. The undeliverable notification is failure
+ the way it is sent. The undeliverable signal is failure
reply sent by the system on behalf of the missing recipient.
Notification::
A message sent to any number of destinations (eg. sent to a group),
@@ -212,14 +230,14 @@ Sending a command to single recipient is slightly more complex. The
sending user sends a message to the receiving one, addressed either by
session ID or by an alias (group to which at most one session may be
subscribed). The message contains the name of the command and
-parameters. It is sent with the undeliverable notifications turned on.
+parameters. It is sent with the undeliverable signals turned on.
The user also starts a timer (with reasonably long timeout). The
sender also subscribes to notifications about terminated sessions or
unsubscription from the alias group.
The receiving user gets the message, runs the command and sends a
response back, with the result. The response has the undeliverable
-notification turned off and it is marked as response to the message
+signal turned off and it is marked as response to the message
containing the command. The sending user receives the answer and pairs
it with the command.
@@ -268,7 +286,8 @@ an error:
{"reply": [1, "You need to fill in other form"]}
And, in this example, the sender is trying to reach an non-existent
-session.
+session. The `msgq` here is not the alias `Msgq`, but a special
+``phantom'' session ID that is not listed anywhere.
s12345 -> s0
{"command": ["ping"]}
@@ -322,6 +341,29 @@ So, this would be an example with unhelpful war council.
s2 -> s12345
{"reply": [0, false]}
s3 -> s12345
+ {"reply": [1, "Advice feature not implemented"]}
+
+Users
+-----
+
+While there's a lot of flexibility for the behaviour of a client, it
+usually comes to something like this (during the lifetime of the
+client):
+
+* The client starts up.
+* The creates one or more sessions (there may be technical reasons to
+ have more than one session, such as threads, but it is not required
+ by the system).
+* It subscribes to some groups to receive notifications in future.
+* It binds to some aliases if it wants to be reachable by others by a
+ nice name.
+* It invokes some start-up commands (to get the configuration, for
+ example).
+* During the lifetime, it listens for notifications and answers
+ commands. It also invokes remote commands and sends notifications
+ about things that are happening.
+* Eventually, the client terminates, closing all the sessions it had
+ opened.
Known limitations
-----------------
@@ -333,7 +375,7 @@ number of transferred messages and the maximum size of message is 4GB,
the code is not optimised and it would probably be very slow.
We currently expect the system not to be at heavy load. Therefore, we
-expect the daemon to keep up with clients sending messages. The
+expect the system to keep up with clients sending messages. The
libraries write in blocking mode, which is no problem if the
expectation is true, as the write buffers will generally be empty and
the write wouldn't block, but if it turns out it is not the case, we
More information about the bind10-changes
mailing list