Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 3998c16fc365199915a8982cb39098416835f670 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
# *****************************************************************************
# * Copyright (c) 2011, 2013 Wind River Systems, Inc. and others.
# * All rights reserved. This program and the accompanying materials
# * are made available under the terms of the Eclipse Public License v1.0
# * which accompanies this distribution, and is available at
# * http://www.eclipse.org/legal/epl-v10.html
# *
# * Contributors:
# *     Wind River Systems - initial API and implementation
# *****************************************************************************

import cStringIO
from .. import protocol, channel
from .task import Task


class DataCache(object):
    """
    Objects of this class are used to cache TCF remote data.
    The cache is asynchronous state machine. The states are:
     1. Valid - cache is in sync with remote data, use getError() and getData()
        to get cached data
     2. Invalid - cache is out of sync, start data retrieval by calling
        validate()
     3. Pending - cache is waiting result of a command that was sent to remote
        peer
     4. Disposed - cache is disposed and cannot be used to store data.

    A cache instance can be created on any data type that needs to be cached.
    Examples might be context children list, context properties, context state,
    memory data, register data, symbol, variable, etc.
    Clients of cache items can register for cache changes, but don't need to
    think about any particular events since that is handled by the cache item
    itself.

    A typical cache client should implement Runnable interface.
    The implementation of run() method should:

    Validate all cache items required for client task.
    If anything is invalid then client should not alter any shared data
    structures, should discard any intermediate results and register (wait) for
    changes of invalid cache instance(s) state.

    When cache item state changes, client is invoked again and full validation
    is restarted.
    Once everything is valid, client completes its task in a single dispatch
    cycle.

    Note: clients should never retain copies of remote data across dispatch
          cycles! Such data would get out of sync and compromise data
          consistency. All remote data and everything derived from remote data
          should be kept in cache items that implement proper event handling
          and can keep data consistent across dispatch cycles.
    """

    __error = None
    __valid = None
    __posted = False
    __disposed = False
    __data = None

    def __init__(self, channel):
        assert channel
        self._channel = channel
        self._command = None
        self.__waiting_list = None

    def post(self):
        if self.__posted:
            return
        if not self.__waiting_list:
            return
        protocol.invokeLater(self)
        self.__posted = True

    def isValid(self):
        """
        @return True if cache contains up-to-date data or error.
        """
        return self.__valid

    def isPending(self):
        """
        @return True if data retrieval command is in progress.
        """
        return self._command is not None

    def isDisposed(self):
        """
        @return True if cache is disposed.
        """
        return self.__disposed

    def getError(self):
        """
        @return error object if data retrieval ended with an error, or None if
        retrieval was successful.
        Note: It is prohibited to call this method when cache is not valid.
        """
        assert self.__valid
        return self.__error

    def getData(self):
        """
        @return cached data object.
        Note: It is prohibited to call this method when cache is not valid.
        """
        assert protocol.isDispatchThread()
        assert self.__valid
        return self.__data

    def __call__(self):
        """
        Notify waiting clients about cache state change and remove them from
        wait list.
        It is responsibility of clients to check if the state change was one
        they are waiting for.
        Clients are not intended to call this method.
        """
        assert protocol.isDispatchThread()
        self.__posted = False
        if self.__waiting_list:
            arr = self.__waiting_list
            self.__waiting_list = None
            for r in tuple(arr):
                if isinstance(r, DataCache):
                    r.post()
                elif isinstance(r, Task) and not r.isDone():
                    r.run()
                else:
                    r()

                arr.remove(r)

            if self.__waiting_list is None:
                self.__waiting_list = arr

    def wait(self, cb):
        """
        Add a client call-back to cache wait list.
        Client call-backs are activated when cache state changes.
        Call-backs are removed from waiting list after that.
        It is responsibility of clients to check if the state change was one
        they are waiting for.
        @param cb - a call-back object
        """
        assert protocol.isDispatchThread()
        assert not self.__disposed
        assert not self.__valid
        if cb and not self.isWaiting(cb):
            if self.__waiting_list is None:
                self.__waiting_list = []
            self.__waiting_list.append(cb)

    def isWaiting(self, cb):
        """
        Return True if a client call-back is waiting for state changes of this
        cache item.
        @param cb - a call-back object.
        @return True if 'cb' is in the wait list.
        """
        if not self.__waiting_list:
            return False
        return cb in self.__waiting_list

    def __validate(self):
        """
        Initiate data retrieval if the cache is not valid.
        @return True if the cache is already valid
        """
        assert protocol.isDispatchThread()
        if self.__disposed or self._channel.getState() != channel.STATE_OPEN:
            self._command = None
            self.__valid = True
            self.__error = None
            self.__data = None
        else:
            if self._command is not None:
                return False
            if not self.__valid and not self.startDataRetrieval():
                return False
        assert self.__valid
        assert self._command is None
        self.post()
        return True

    def validate(self, cb=None):
        """
        If the cache is not valid, initiate data retrieval and
        add a client call-back to cache wait list.
        Client call-backs are activated when cache state changes.
        Call-backs are removed from waiting list after that.
        It is responsibility of clients to check if the state change was one
        they are waiting for.
        If the cache is valid do nothing and return True.
        @param cb - a call-back object (optional)
        @return True if the cache is already valid
        """
        if not self.__validate():
            self.wait(cb)
            return False
        return True

    def start(self, command):
        """
        Start cache pending state.
        Pending state is when the cache is waiting for a TCF command to return
        results.
        @param command - TCF command handle.
        """
        assert not self.__valid
        assert command
        assert self._command is None
        self._command = command

    def done(self, command):
        """
        End cache pending state, but not mark the cache as valid.
        @param command - TCF command handle.
        """
        if self._command is not command:
            return
        assert not self.__valid
        self._command = None
        self.post()

    def set(self, token, error, data):
        """
        End cache pending state and mark the cache as valid.
        If 'token' != None, the data represent results from a completed
        command.
        The data should be ignored if current cache pending command is not same
        as 'token'.
        It can happen if the cache was reset or canceled during data retrieval.
        @param token - pending command handle or None.
        @param error - data retrieval error or None
        @param data - up-to-date data object
        """
        assert protocol.isDispatchThread()
        if token and self._command is not token:
            return
        self._command = None
        if not self.__disposed:
            assert not self.__valid
            if self._channel.getState() != channel.STATE_OPEN:
                self.__error = None
                self.__data = None
            self.__error = error
            self.__data = data
            self.__valid = True
        self.post()

    def reset(self, data=None):
        """
        Force cache to become valid, cancel pending data retrieval if data is
        provided.
        @param data - up-to-date data object (optional)
        """
        assert protocol.isDispatchThread()
        if data is not None and self._command is not None:
            self._command.cancel()
            self._command = None
        if not self.__disposed:
            self.__data = data
            self.__error = None
            self.__valid = True
        self.post()

    def cancel(self):
        """
        Invalidate the cache.
        Cancel pending data retrieval if any.
        """
        self.reset()
        if self._command is not None:
            self._command.cancel()
            self._command = None

    def dispose(self):
        """
        Dispose the cache.
        Cancel pending data retrieval if any.
        """
        self.cancel()
        self.__valid = True
        self.__disposed = True

    def __str__(self):
        bf = cStringIO.StringIO()
        bf.write('[')
        if self.__valid:
            bf.append("valid,")
        if self.__disposed:
            bf.write("disposed,")
        if self.__posted:
            bf.write("posted,")
        if self.__error is not None:
            bf.write("error,")
        bf.write("data=")
        bf.write(str(self.__data))
        bf.write(']')
        return bf.getvalue()

    def startDataRetrieval(self):
        """
        Sub-classes should override this method to implement actual data
        retrieval logic.
        @return True is all done, False if retrieval is in progress.
        """
        raise NotImplementedError("Abstract method")

Back to the top