Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: c8f5d56eab2389f3d7bc71f45f8b79b9d93418fe (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
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
# *****************************************************************************
# * 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
# *****************************************************************************

"""Streams service is a generic interface to support streaming of data between
host and remote agents.

.. |connect| replace:: :meth:`~StreamsService.connect`
.. |disconnect| replace:: :meth:`~StreamsService.disconnect`
.. |eos| replace:: :meth:`~StreamsService.eos`
.. |processes| replace:: :mod:`~tcf.services.processes`
.. |read| replace:: :meth:`~StreamsService.read`
.. |subscribe| replace:: :meth:`~StreamsService.subscribe`
.. |terminals| replace:: :mod:`~tcf.services.terminals`
.. |unsubscribe| replace:: :meth:`~StreamsService.unsubscribe`
.. |write| replace:: :meth:`~StreamsService.write`
.. |DoneConnect| replace:: :class:`DoneConnect`
.. |DoneDisconnect| replace:: :class:`DoneDisconnect`
.. |DoneEOS| replace:: :class:`DoneEOS`
.. |DoneRead| replace:: :class:`DoneRead`
.. |DoneSubscribe| replace:: :class:`DoneSubscribe`
.. |DoneUnsubscribe| replace:: :class:`DoneUnsubscribe`
.. |DoneWrite| replace:: :class:`DoneWrite`
.. |StreamsListener| replace:: :class:`StreamsListener`

The service supports:
 1. Asynchronous overlapped data streaming: multiple |read| or |write| command
    can be issued at same time, both peers can continue data processing
    concurrently with data transmission.
 2. Multicast: multiple clients can receive data from same stream.
 3. Subscription model: clients are required to expressed interest in
    particular streams by subscribing for the service.
 4. Flow control: peers can throttle data flow of individual streams by
    delaying |read| and |write| commands.

Service Methods
---------------
.. autodata:: NAME
.. autoclass:: StreamsService

connect
^^^^^^^
.. automethod:: StreamsService.connect

disconnect
^^^^^^^^^^
.. automethod:: StreamsService.disconnect

eos
^^^
.. automethod:: StreamsService.eos

getName
^^^^^^^
.. automethod:: StreamsService.getName

read
^^^^
.. automethod:: StreamsService.read

subscribe
^^^^^^^^^
.. automethod:: StreamsService.subscribe

unsubscribe
^^^^^^^^^^^
.. automethod:: StreamsService.unsubscribe

write
^^^^^
.. automethod:: StreamsService.write

Callback Classes
----------------
DoneConnect
^^^^^^^^^^^
.. autoclass:: DoneConnect
    :members:

DoneDisconnect
^^^^^^^^^^^^^^
.. autoclass:: DoneDisconnect
    :members:

DoneEOS
^^^^^^^
.. autoclass:: DoneEOS
    :members:

DoneRead
^^^^^^^^
.. autoclass:: DoneRead
    :members:

DoneSubscribe
^^^^^^^^^^^^^
.. autoclass:: DoneSubscribe
    :members:

DoneUnsubscribe
^^^^^^^^^^^^^^^
.. autoclass:: DoneUnsubscribe
    :members:

DoneWrite
^^^^^^^^^
.. autoclass:: DoneWrite
    :members:

Listener
--------
.. autoclass:: StreamsListener
    :members:
"""

from .. import services

NAME = "Streams"
"""Streams service name."""


class StreamsService(services.Service):
    """TCF Streams service interface."""

    def getName(self):
        """Get this service name.

        :returns: A |basestring| representing this service name, which is the
                  value of :const:`NAME`
        """
        return NAME

    def subscribe(self, stream_type, listener, done):
        """Clients must subscribe for one or more stream types to be able to
        send or receive stream data.

        Subscribers receive notifications when a stream of given type is
        created or disposed.

        Subscribers are required to respond with |read| or |disconnect|
        commands as necessary.

        .. note:: It is up to each service to implement its stream type if
                  required. For opensource services, |processes| uses
                  ``Processes`` for stream type, and |terminals| uses
                  ``Terminals``

        :param stream_type: The stream source type.
        :type stream_type: |basestring|
        :param listener: Client implementation of StreamsListener interface.
        :type listener: |StreamsListener|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneSubscribe|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def unsubscribe(self, stream_type, listener, done):
        """Unsubscribe the client from given stream source type.

        .. note:: It is up to each service to implement its stream type if
                  required. For opensource services, |processes| uses
                  ``Processes`` for stream type, and |terminals| uses
                  ``Terminals``

        :param stream_type: The stream source type.
        :param listener: Client implementation of StreamsListener interface.
        :type listener: |StreamsListener|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneUnsubscribe|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def read(self, stream_id, size, done):
        """Read data from a stream. If stream buffer is empty, the command will
        wait until data is available.

        Remote peer will continue to process other commands while |read|
        command is pending.

        Client can send more |read| commands without waiting for the first
        command to complete.

        Doing that improves communication channel bandwidth utilization.
        Pending |read| commands will be executed in same order as issued.

        Client can delay sending of |read| command if it is not ready to
        receive more data, however, delaying for too long can cause stream
        buffer overflow and lost of data.

        :param stream_id: ID of the stream to read from.
        :type stream_id: |basestring|
        :param size: Max number of bytes to read.
        :type size: |int|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneRead|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def write(self, stream_id, buf, offset, size, done):
        """Write data to a stream. If stream buffer is full, the command will
        wait until space is available.

        Remote peer will continue to process other commands while |write|
        command is pending.

        Client can send more |write| commands without waiting for the first
        command to complete. Doing that improves communication channel
        bandwidth utilization.

        Pending |write| commands will be executed in same order as issued.

        :param stream_id: ID of the stream to write to.
        :type stream_id: |basestring|
        :param buf: Buffer that contains stream data.
        :type buf: |bytearray|
        :param offset: Byte offset in the buffer.
        :type offset: |int|
        :param size: Number of bytes to write.
        :type size: |int|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneWrite|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def eos(self, stream_id, done):
        """Send End Of Stream marker to a stream.

        No more writing to the stream is allowed after that.

        :param stream_id: ID of the stream to senf EOS to.
        :type stream_id: |basestring|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneEOS|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def connect(self, stream_id, done):
        """Connect client to a stream.

        Some data might be dropped from the stream by the time |connect|
        command is executed.

        Client should be able to re-sync with stream data if it wants to read
        from such stream.

        If a client wants to read a stream from the beginning it should use
        |subscribe| command instead of |connect|.

        :param stream_id: ID of the stream to connect to.
        :type stream_id: |basestring|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneConnect|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def disconnect(self, stream_id, done):
        """Disconnect client from a stream.

        :param stream_id: ID of the stream to disconnect from.
        :type stream_id: |basestring|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneDisconnect|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")


class StreamsListener(object):
    """Clients can implement StreamsListener interface to be notified
    when a stream is created or disposed.

    The interface is registered with |subscribe| command.

    When new stream is created, client must decide if it is interested in that
    particular stream instance.

    If not interested, client should send |disconnect| command to allow remote
    peer to free resources and bandwidth.

    If not disconnected, client is required to send |read| commands as
    necessary to prevent stream buffer overflow.
    """

    def created(self, stream_type, stream_id, context_id):
        """Called when a new stream is created.

        .. note:: It is up to each service to implement its stream type if
                  required. For opensource services, |processes| uses
                  ``Processes`` for stream type, and |terminals| uses
                  ``Terminals``

        :param stream_type: Source type of the stream.
        :type stream_type: |basestring|
        :param stream_id: ID of the created stream.
        :type stream_id: |basestring|
        :param context_id: a context ID that is associated with the stream,
                           or **None**. Exact meaning of the context ID depends
                           on stream type. Stream types and context IDs are
                           defined by services that use Streams service to
                           transmit data
        """
        pass

    def disposed(self, stream_type, stream_id):
        """Called when a stream is disposed.

        .. note:: It is up to each service to implement its stream type if
                  required. For opensource services, |processes| uses
                  ``Processes`` for stream type, and |terminals| uses
                  ``Terminals``

        :param stream_type: Source type of the stream.
        :type stream_type: |basestring|
        :param stream_id: ID of the disposed stream.
        :type stream_id: |basestring|
        """
        pass


class DoneSubscribe(object):
    """Call back interface for |subscribe| command."""

    def doneSubscribe(self, token, error):
        """Called when stream subscription is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        """
        pass


class DoneUnsubscribe(object):
    """Call back interface for |unsubscribe| command."""

    def doneUnsubscribe(self, token, error):
        """Called when stream unsubscription is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        """
        pass


class DoneRead(object):
    """Call back interface for |read| command."""

    def doneRead(self, token, error, lost_size, data, eos):
        """Called when |read| command is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        :param lost_size: Number of bytes that were lost because of buffer
                          overflow. A *lost_size* of **-1** means unknown
                          number of bytes were lost. If both *lost_size* and
                          *data.length* are non-zero then lost bytes are
                          considered located right before read bytes.
        :type lost_size: |int|
        :param data: Bytes read from the stream.
        :type data: |bytearray|
        :param eos: **True** if end of stream was reached.
        :type eos: |bool|
        """
        pass


class DoneWrite(object):
    """Call back interface for |write| command."""

    def doneWrite(self, token, error):
        """Called when |write| command is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        """
        pass


class DoneEOS(object):
    """Call back interface for |eos| command."""

    def doneEOS(self, token, error):
        """Called when |eos| command is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        """
        pass


class DoneConnect(object):
    """Call back interface for |connect| command."""

    def doneConnect(self, token, error):
        """Called when |connect| command is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        """
        pass


class DoneDisconnect(object):
    """Call back interface for |disconnect| command."""

    def doneDisconnect(self, token, error):
        """Called when |disconnect| command is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        """
        pass

Back to the top