projects / thirdparty / squid.git / blame
| Commit | Line | Data |
|---|---|---|
| 9a1b46cc | 1 | /* |
| bde978a6 | 2 | * Copyright (C) 1996-2015 The Squid Software Foundation and contributors |
| 9a1b46cc AJ |
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 | ||
| 946b016d AR |
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 | |
| 0d4e382b | 64 | call-specific APIs when possible (e.g., Comm::ReadCancel or comm_close). |
| 946b016d AR |
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 | */ |