From: Michal 'vorner' Vaner Date: Thu, 25 Apr 2013 11:32:39 +0000 (+0200) Subject: [2738] Remove ipc-high-2 X-Git-Tag: bind10-1.1.0beta2-release~8^2~17^2~4 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=73feee77d8a05f458c90990c8ff95f3338c54d72;p=thirdparty%2Fkea.git [2738] Remove ipc-high-2 It was mostly an example and is now merged to the base version. No longer needed. --- diff --git a/doc/design/ipc-high-2.txt b/doc/design/ipc-high-2.txt deleted file mode 100644 index 6c34554156..0000000000 --- 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