summaryrefslogtreecommitdiff
path: root/src/lib/efl/interfaces/efl_io_buffer.eo
blob: 518a799a3a763c33092f3b74e13019cae2694da3 (plain)
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
class @beta Efl.Io.Buffer extends Efl.Object
                          implements Efl.Io.Reader, Efl.Io.Writer, Efl.Io.Closer, Efl.Io.Sizer, Efl.Io.Positioner {
    [[Generic In-memory buffer of data to be used as I/O.

      This class offers both input and output, which can be used at
      the same time since @Efl.Io.Reader.read and @Efl.Io.Writer.write
      use different offsets/position internally.

      One can get temporary direct access to internal buffer with
      @.slice or steal the buffer with @.binbuf_steal.

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

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

        adopt_readonly {
            [[Adopt a read-only slice as buffer's backing store.

              The slice memory will not be copied and must remain
              alive during the buffer's lifetime. Usually this is
              guaranteed by some global static-const memory or some
              parent object and this buffer being a view of that -- be
              aware of parent memory remaining alive, such as
              "slice,changed" events.
            ]]
            params {
                @in slice: const(Eina.Slice); [[Slice to adopt as read-only]]
            }
        }

        adopt_readwrite {
            [[Adopt a read-write slice as buffer's backing store.

              The slice memory will not be copied and must remain
              alive during the buffer's lifetime. Usually this is
              guaranteed by some global static memory or some
              parent object and this buffer being a view of that -- be
              aware of parent memory remaining alive, such as
              "slice,changed" events.

              The memory will be disposed using free() and reallocated
              using realloc().
            ]]
            params {
                @in slice: Eina.Rw_Slice; [[Slice to adopt as read-write]]
            }
        }

        @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 position_read {
            [[The position used by @Efl.Io.Reader.read.

             Note that @Efl.Io.Positioner.seek or
             @Efl.Io.Positioner.position.set will affect this property
             and @.position_write.

             @Efl.Io.Positioner.position.get will return the greatest
             of @.position_read and @.position_write.
            ]]
            get { }
            set {
                return: bool (false); [[$true if setting the position succeeded, $false otherwise]]
            }
            values {
                position: uint64; [[Position in buffer]]
            }
        }

        @property position_write {
            [[The position used by @Efl.Io.Writer.write.

             Note that @Efl.Io.Positioner.seek or
             @Efl.Io.Positioner.position.set will affect this property
             and @.position_read.

             @Efl.Io.Positioner.position.get will return the greatest
             of @.position_read and @.position_write.
            ]]
            get { }
            set {
                return: bool (false); [[$true if setting the position succeeded, $false otherwise]]
            }
            values {
                position: uint64; [[Position in buffer]]
            }
        }

        @property slice {
            [[Get a temporary access to buffer's internal memory.

              The memory pointed by slice may be changed by other
              methods of this class. The event "reallocated" 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.Sizer.resize are called.
                                     It is the full slice, not a partial one starting at current position.]]
            }
        }

        binbuf_steal {
            [[Steals the internal buffer memory and returns it as a binbuf.

              The returned memory must be freed with eina_binbuf_free().

              On failure, for example a read-only backing store was
              adopted with @.adopt_readonly, $NULL is returned.
            ]]
            return: ptr(Eina.Binbuf) @move @no_unused; [[Binbuf]]
        }
    }

    events {
       position_read,changed: void; [[Notifies @.position_read changed]]
       position_write,changed: void; [[Notifies @.position_write changed]]
       reallocated: void; [[Notifies the internal buffer was reallocated, thus whatever was returned by @.slice
                            becomes invalid.]]
    }

    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_invalidate { get; set; }
        Efl.Io.Sizer.resize;
        Efl.Io.Sizer.size { get; }
        Efl.Io.Positioner.seek;
        Efl.Io.Positioner.position { get; }
    }
}