summaryrefslogtreecommitdiff
path: root/src/lib/efl/interfaces/efl_io_queue.eo
blob: 46bcde493f41bcdb981c91c0fcfa2c61c7f83511 (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
class Efl.Io.Queue (Efl.Object, Efl.Io.Reader, Efl.Io.Writer, Efl.Io.Closer) {
    [[Generic In-memory queue of data to be used as I/O.

      This class is to be used to receive temporary data using
      @Efl.Io.Writer.write and hold it until someone calls
      @Efl.Io.Reader.read to consume it.

      A fixed sized queue can be implemented by setting @.limit
      followed by @.preallocate

      @since 1.19
    ]]

    methods {
        preallocate {
            [[Immediately pre-allocate a buffer of at least a given size.]]
            params {
                @in size: size; [[Amount of bytes to pre-allocate.]]
            }
        }

        @property limit {
            [[Limit how big the buffer can grow.

              This affects both @.preallocate and how buffer grows
              when @Efl.Io.Writer.write is called.

              If you want a buffer of an exact size, always set the
              limit before any further calls that can expand it.
            ]]
            get { }
            set {
                [[Constructor-only property to set buffer limit. 0 is unlimited]]
            }
            values {
                size: size; [[Defines a maximum buffer size, or 0 to allow unlimited amount of bytes]]
            }
        }

        @property usage {
            [[How many bytes are available for read]]
            get { }
            values {
                usage: size; [[Bytes available to read]]
            }
        }

        @property slice {
            [[Gain temporary access to queue's internal read memory.

              The memory pointed to by slice may be changed by other
              methods of this class. The event "slice,changed" will be
              called in those situations.
            ]]
            get { }
            values {
                slice: Eina.Slice; [[Slice of the current buffer, may be invalidated if @Efl.Io.Writer.write, @Efl.Io.Closer.close or @Efl.Io.Reader.read are called. It is the full slice available for reading.]]
            }
        }

        discard {
            [[Discard the given number of bytes.

              This has the same effect as reading and discarding the
              given amount of bytes, without executing the actual
              copy.

              It's often paired with @.slice, if users read the
              information from the slice and once they're done, that
              data must be discarded.

              As an example, some protocols provide messages with a
              "size" header, in which case @.slice is used to peek into the
              available memory to see if there is a "size" and if the
              rest of the slice is the full payload. In that situation the
              slice may be handled by a processing function. When
              the function is complete the defined amount of data must be
              discarded -- with this function.
            ]]
            params {
                amount: size; [[Bytes to discard]]
            }
        }

        clear {
            [[Clears the queue. Same as reading all data.

              This is equivalent to calling @.discard with @.usage
              amount of bytes.
            ]]
        }

        eos_mark {
            [[Mark this end-of-stream.

              That will set @Efl.Io.Reader.eos to $true and forbid any
              further writes.

              Unlike @Efl.Io.Closer.close, this won't clear anything.
            ]]
        }
    }

    events {
        slice,changed; [[The read-slice returned by @.slice may have changed.]]
    }

    implements {
        Efl.Object.finalize;
        Efl.Object.destructor;
        Efl.Io.Reader.read;
        Efl.Io.Reader.can_read { get; set; }
        Efl.Io.Reader.eos { get; set; }
        Efl.Io.Writer.write;
        Efl.Io.Writer.can_write { get; set; }
        Efl.Io.Closer.close;
        Efl.Io.Closer.closed { get; }
        Efl.Io.Closer.close_on_exec { get; set; }
        Efl.Io.Closer.close_on_destructor { get; set; }
    }
}