lnet/doc/Message-life-cycle

   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.
   4
   5
   6 Put request
   7 -----------
   8
   9 1.  NAL notices that there is a incoming message header on the network
  10 and reads an ptl_hdr_t in from the wire.
  11
  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
  14 later.
  15
  16 3.  The NAL calls lib_parse() with a pointer to the header and its
  17 private data structure.
  18
  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.
  24
  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.
  28
  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.
  32
  33
  34
  35 Get request
  36 -----------
  37
  38 1.  As with a Put, the NAL notices the incoming message header and
  39 passes it to lib_parse().
  40
  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.
  46
  47 3.  The library may build a message state object to possibly
  48 write an event log or invalidate a memory region.
  49
  50 4.  The library will build a ptl_msg_t header that specifies the
  51 Portals protocol information for delivery at the remote end.
  52
  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
  56 other things.
  57
  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.
  62
  63 7.  And then return to the library.
  64
  65
  66 Reply request
  67 -------------
  68
  69 1.  Starting at "The library decodes the header..."
  70
  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.
  74
  75
  76 Ack request
  77 -----------
  78
  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.
  82
  83
  84 Packet arrival
  85 --------------
  86
  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
  90 given to nal->recv().
  91
  92         How this happens is outside the scope of the Portals library
  93         and soley determined by the NAL...
  94
  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.
 100
 101 3.  It should then clean up any remaining NAL specific state about
 102 the message and go back into the main loop.
 103
 104
 105 Outgoing packets
 106 ----------------
 107
 108 1.  When the NAL has pending output, it should put the packets on
 109 the wire wrapped with whatever implementation specified wrappers.
 110
 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
 115 entries.
 116
 117
 118