ocean.time.timeout.model.ITimeoutManager source code

1 /*******************************************************************************
2 
3     Timeout manager interface
4 
5     The reason for this interface is to avoid requiring an application to be
6     linked against the libebtree, which is required by TimeoutManager and
7     ExpiryRegistration, when it uses a library module that supports a timeout
8     functionality as an optional feature.
9     Therefore, library modules that support a timeout functionality as an
10     optional feature should always use this interface and not import
11     TimeoutManager/ExpiryRegistration.
12 
13     Copyright:
14         Copyright (c) 2009-2016 dunnhumby Germany GmbH.
15         All rights reserved.
16 
17     License:
18         Boost Software License Version 1.0. See LICENSE_BOOST.txt for details.
19         Alternatively, this file may be distributed under the terms of the Tango
20         3-Clause BSD License (see LICENSE_BSD.txt for details).
21 
22 *******************************************************************************/
23 
24 module ocean.time.timeout.model.ITimeoutManager;
25 
26 
27 import ocean.time.timeout.model.ITimeoutClient,
28        ocean.time.timeout.model.IExpiryRegistration : IExpiryRegistration;
29 
30 /******************************************************************************/
31 
32 interface ITimeoutManager
33 {
34     /***************************************************************************
35 
36         Tells the wall clock time time when the next client will expire.
37 
38         Returns:
39             the wall clock time when the next client will expire as UNIX time
40             in microseconds or ulong.max if no client is currently registered.
41 
42     ***************************************************************************/
43 
44     ulong next_expiration_us ( );
45 
46     /***************************************************************************
47 
48         Tells the time until the next client will expire.
49 
50         Returns:
51             the time left until next client will expire in microseconds or
52             ulong.max if no client is currently registered. 0 indicates that
53             there are timed out clients that have not yet been notified and
54             unregistered.
55 
56     ***************************************************************************/
57 
58     ulong us_left ( );
59 
60     /***************************************************************************
61 
62         Checks for timed out clients. For any timed out client its timeout()
63         method is called, then it is unregistered, finally dg() is called with
64         it as argument.
65 
66         This method should be called when the timeout set by setTimeout() has
67         expired.
68 
69         If dg returns false to cancel, the clients iterated over so far are
70         removed. To remove the remaining clients, call this method again.
71 
72         Params:
73             dg = optional callback delegate that will be called with each timed
74                  out client and must return true to continue or false to cancel.
75 
76         Returns:
77             the number of expired clients.
78 
79     ***************************************************************************/
80 
81     size_t checkTimeouts ( scope bool delegate ( ITimeoutClient client ) dg );
82 
83     /***************************************************************************
84 
85         Registers client with the timeout manager and returns the expiry
86         registration object which the registered client is associated to.
87 
88         Note: Depending on the implementation, this method may return a newly
89               created object that should be kept and reused by the application.
90               It is also application dependent whether the client remains
91               associated to the expiry registration object after it has been
92               unregistered from the timeout manager or not.
93 
94         Params:
95             client = client to register
96 
97         Returns:
98             expiry registration object.
99 
100     ***************************************************************************/
101 
102     IExpiryRegistration getRegistration ( ITimeoutClient client );
103 }
104