WINGs/Documentation/README.connection

   1 Methods of handling WMConnectionDidDieNotification notification events
   2 (same for WMConnectionDidTimeoutNotification)
   3 ----------------------------------------------------------------------
   4
   5 Once your program got this notification (you need to install an observer for
   6 it), there are some ways to handle it:
   7
   8 1. Make your observer enqueue a new notification in the ASAP queue, and the
   9    observer for this new notification (it can be the same function if you
  10    arrange to distinguish between the two cases), should remove the connection.
  11    You can also close the connection before enqueuing the new notification to
  12    the ASAP queue, but is not strictly necessarily, since it will be closed
  13    when the observer for the new enqueued notification will be called and you
  14    will call the close/remove function there. This is just to make sure your
  15    connection will be silent, and won't generate new events until you reach
  16    that point.
  17    This is by far the best method, since it will assure you that if you
  18    enqueue more than one notification to remove the same connection, they will
  19    be coalesced, and called only once.
  20
  21 2. In your observer, put the died/closed connection in an array or bag, and
  22    destroy all the connections present in the array/bag, in your main loop,
  23    after you call the  WHandleEvents()/WMHandleEvent(). Also closing the
  24    connection can be done before putting the connection in the array/bag, but
  25    is optional as noted above. In this case you need to make sure you don't
  26    put in the array/bag the same connection more than once, in case the
  27    DieNotification is sent more that once to you. This is automagically solved
  28    by method 1.
  29
  30 3. In case it's your only connection, and you plan to exit if it was closed or
  31    died, then you can safely close/remove it, and exit. As long as you no
  32    longer access it, there is no problem.
  33
  34 4. Make you observer remove the connection. Then make sure that after that
  35    point your code no longer tries to access that connection (this usually
  36    means until your code gets back to the main loop). This is almost always
  37    very hard to achive and subject to hidden errors. I do not recommend this
  38    way of handling the died notification. It is ugly and very complicated to
  39    handle if the program is in a very deeply nested function when it finds out
  40    that the connection died. If you use it and get plenty of SIGSEGVs then you
  41    know why. This method was not presented here to be used, but to show what
  42    should be avoided in dealing with the died notification, in case someone
  43    gets the idea to try it this way.
  44
  45
  46 Note:  read/write operations means to use our read/write functions (like
  47        WMGetMessage()/WMSendMessage()), not the C library ones read()/write().
  48 Note2: removing a connection is done by WMDestroyConnection(), while
  49        WMCloseConnection() only closes the socket, and removed any pending
  50        queues and timers on the connection.
  51