src/base/AsyncCalls.dox

   1 /*
   2  * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 /**
  10 \defgroup AsyncCalls Asynchronous Calls
  11 \ingroup Components
  12
  13
  14 \section Terminology Terminology
  15
  16 - \b Call: an AsyncCall object meant to be delivered from the Caller to the
  17   Recipient.
  18 - \b Recipient: the code being the destination of the Call. The specific
  19   function receiving the call is often called "handler".
  20 - \b Caller: the code scheduling or placing the Call.
  21 - \b Creator: the code creating the Call.
  22 - \b Dialing: the final act of delivering the Call to the Recipient.
  23 - \b Canceling: preventing the call from being dialed in the future.
  24 - <b>Pending call</b>: the call which has been scheduled but no attempt to dial
  25   it has been made.
  26 - <b>Live call</b>: the in-progress call that has been dialed and the Recipient
  27   (receiving) function has not finished yet.
  28
  29
  30 \section Life Typical life cycle
  31
  32 -# Creator creates a Call object and stores its pointer, possibly in a
  33 temporary variable. If Creator is the future Recipient of the Call, it
  34 is customary to talk about a "callback". In such context, Creator gives
  35 the Call pointer to some other code (the future Caller). Calls are
  36 refcounted and the AsyncCall::Pointer class must be used to point and
  37 share them.
  38 -# Time passes and something triggers the need to dial the call.
  39 -# Caller schedules (a.k.a, places) the Call. The Call is placed in the
  40 AsyncCallQueue. The queue preserves the scheduling call order.
  41 -# Time passes and it is now time to dial the call.
  42 -# AsyncCallQueue checks whether the call can be dialed. If yes,
  43 AsyncCallQueue dials the Call and the Recipient receives it. Otherwise,
  44 only a debugging message is logged (if enabled). Dialing a call involves
  45 several state checks at several stages, depending on the Call type.
  46 -# The Call is alive while the Recipient is handling it. That state ends
  47 when the Recipient code (a.k.a., handler) returns. At that point, the
  48 AsyncCallQueue proceeds to handle other calls.
  49 -# The Call object is destroyed when the last reference to it is gone.
  50 One should not try to invalidate or delete the call.
  51
  52
  53 \section Rules Basic rules
  54
  55 - Callbacks must be called: If a Caller has a Call pointer as a
  56 callback, the Caller must make that Call when conditions are right
  57 (possibly with a call-specific error indicator). Whether that Call will
  58 be dialed is irrelevant here.
  59
  60 - Unwanted calls must be canceled: If Recipient may not be able to
  61 handle the call back, then it must cancel it.  Whether that Call will be
  62 scheduled is irrelevant here. If the Recipient has an AsyncCall pointer,
  63 calling AsyncCall::cancel is sufficient, but the code should use
  64 call-specific APIs when possible (e.g., Comm::ReadCancel or comm_close).
  65
  66 - Processed calls should be forgotten: If you scheduled, received, or
  67 cancel the call, set its pointer to NULL. The Caller should forget the
  68 call after scheduling it. the recipient should forget the call when it
  69 receives or cancels it. These are just cleanup rules to avoid
  70 double-scheduling or double-cancellation as well as situations where the
  71 code assumes it can still change a pending Call (which will not work for
  72 SMP code).
  73
  74 - The calls are received in the order they were scheduled.
  75
  76 - The Recipient is guaranteed to receive at most one Call at a time. An
  77 attempt to dial call B while some call A is alive is a bug, and call B
  78 will not be dialed.
  79
  80
  81 \section Canceling Call Canceling
  82
  83 - A call may be canceled at any time.
  84
  85 - A canceled call will not be dialed.
  86
  87 - Cancellation has immediate effect: The call will never be dialed
  88 after cancel() is called
  89
  90 - Cancellation by non-Recipients is discouraged because it may not work
  91 in an SMP environment.
  92
  93 - A late call cancellation is cancellation that is performed after the Call
  94 has already been dialed (i.e., the call is or was alive at the time of the
  95 cancellation).  Late cancellation is a no-op. It is not a bug to cancel
  96 something late, but the canceling code should be aware of that possibility.
  97
  98
  99 */