1 This documents the life cycle of message as it arrives and is handled by
2 a basic async, packetized NAL. There are four types of messages that have
3 slightly different life cycles, so they are addressed independently.
9 1. NAL notices that there is an incoming message header on the network
10 and reads an ptl_hdr_t in from the wire.
12 2. It may store additional NAL specific data that provides context
13 for this event in a void* that it will interpret in some fashion
16 3. The NAL calls lib_parse() with a pointer to the header and its
17 private data structure.
19 4. The library decodes the header and may build a message state
20 object that describes the event to be written and the ACK to be
21 sent, if any. It then calls nal->recv() with the private data
22 that the NAL passed in, a pointer to the message state object
23 and a translated user address.
25 The NAL will have been given a chance to pretranslate
26 all user addresses when the buffers are created. This
27 process is described in the NAL-HOWTO.
29 5. The NAL should restore what ever context it required from the
30 private data pointer, begin receiving the bytes and possibly store
31 some extra state of its own. It should return at this point.
38 1. As with a Put, the NAL notices the incoming message header and
39 passes it to lib_parse().
41 2. The library decodes the header and calls nal->recv() with a
42 zero byte length, offset and destination to instruct it to clean
43 up the wire after reading the header. The private data will
44 be passed in as well, allowing the NAL to retrieve any state
45 or context that it requires.
47 3. The library may build a message state object to possibly
48 write an event log or invalidate a memory region.
50 4. The library will build a ptl_msg_t header that specifies the
51 Portals protocol information for delivery at the remote end.
53 5. The library calls nal->send() with the pre-built header,
54 the optional message state object, the four part address
55 component, a translated user pointer + offset, and some
58 6. The NAL is to put the header on the wire or copy it at
59 this point (since it off the stack). It should store some
60 amount of state about its current position in the message and
61 the destination address.
63 7. And then return to the library.
69 1. Starting at "The library decodes the header..."
71 2. The library decodes the header and calls nal->recv()
72 to bring in the rest of the message. Flow continues in
73 exactly the same fashion as with all other receives.
79 1. The library decodes the header, builds the appropriate data
80 structures for the event in a message state object and calls nal->recv()
81 with a zero byte length, etc.
87 1. The NAL should notice the arrival of a packet, retrieve whatever
88 state it needs from the message ID or other NAL specific header data
89 and place the data bytes directly into the user address that were
92 How this happens is outside the scope of the Portals library
93 and soley determined by the NAL...
95 2. If this is the last packet in a message, the NAL should retrieve
96 the lib_msg_t *cookie that it was given in the call to nal->recv()
97 and pass it to lib_finalize(). lib_finalize() may call nal->send()
98 to send an ACK, nal->write() to record an entry in the event log,
99 nal->invalidate() to unregister a region of memory or do nothing at all.
101 3. It should then clean up any remaining NAL specific state about
102 the message and go back into the main loop.
108 1. When the NAL has pending output, it should put the packets on
109 the wire wrapped with whatever implementation specified wrappers.
111 2. Once it has output all the packets of a message it should
112 call lib_finalize() with the message state object that was
113 handed to nal->send(). This will allows the library to clean
114 up its state regarding the message and write any pending event