forked from enlightenment/efl
Eo docs: update for grammar and readability
This commit is contained in:
parent
26acc9bea2
commit
e942dd6420
|
@ -2,7 +2,7 @@
|
|||
|
||||
struct Ecore.Exe.Event_Data.Line
|
||||
{
|
||||
[[A structure that stores information of lines data from a child process.]]
|
||||
[[A structure which stores information on lines data from a child process.]]
|
||||
line: ptr(char); [[The bytes of a line of buffered data]]
|
||||
size: int; [[The size of the line buffer in bytes]]
|
||||
}
|
||||
|
@ -15,9 +15,9 @@ struct Ecore.Exe.Event_Data
|
|||
{
|
||||
[[Ecore exe event data structure]]
|
||||
exe: Efl.Object; [[The handle to the process. FIXME: should actually be Ecore.Exe, workaround cyclic]]
|
||||
data: void_ptr; [[The raw binary data from the child process that was received]]
|
||||
data: void_ptr; [[The raw binary data from the child process received]]
|
||||
size: int; [[The size of this data in bytes]]
|
||||
lines: ptr(Ecore.Exe.Event_Data.Line); [[An array of line data if line buffered, the last one has its line member set to $NULL]]
|
||||
lines: ptr(Ecore.Exe.Event_Data.Line); [[An array of line data if line buffered. The last one has its line member set to $NULL]]
|
||||
}
|
||||
|
||||
enum Ecore.Exe_Flags
|
||||
|
@ -34,7 +34,7 @@ enum Ecore.Exe_Flags
|
|||
pipe_auto = 32, [[stdout and stderr are buffered automatically]]
|
||||
respawn = 64, [[FIXME: Exe is restarted if it dies]]
|
||||
use_sh = 128, [[Use /bin/sh to run the command.]]
|
||||
not_leader = 256, [[Do not use setsid() to have the executed process be its own session leader]]
|
||||
not_leader = 256, [[Do not use setsid() to set the executed process as its own session leader]]
|
||||
term_with_parent = 512, [[Makes child receive SIGTERM when parent dies.]]
|
||||
isolate_io = 1024, [[Try and isolate stdin/out and err of the process so it isn't shared with the parent.]]
|
||||
}
|
||||
|
@ -43,8 +43,8 @@ class Ecore.Exe (Efl.Object, Efl.Control)
|
|||
{
|
||||
[[Ecore.Exe is responsible for managing portable process spawning.
|
||||
|
||||
With this module you are able to spawn, pause and quit the spawned processes.
|
||||
An interaction between your process and those spawned is possible using pipes or signals.
|
||||
With this module you are able to spawn, pause and quit spawned processes.
|
||||
Interaction between your process and those spawned is possible using pipes or signals.
|
||||
]]
|
||||
|
||||
legacy_prefix: ecore_exe;
|
||||
|
|
|
@ -1,31 +1,31 @@
|
|||
class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, Efl.Io.Closer) {
|
||||
[[A wrapper object offering an easy to use, buffered streams over existing I/O class.
|
||||
[[A wrapper object offering easy to use buffered streams over existing I/O class.
|
||||
|
||||
The buffered stream encapsulates an actual @Efl.Io.Reader or
|
||||
@Efl.Io.Writer, an input @Efl.Io.Queue, an output @Efl.Io.Queue
|
||||
and these are linked using a input and a output
|
||||
@Efl.Io.Writer, an input @Efl.Io.Queue and an output @Efl.Io.Queue.
|
||||
These are linked using a input and a output
|
||||
@Efl.Io.Copier.
|
||||
|
||||
The idea is that unlike traditional @Efl.Io.Writer that will
|
||||
The idea is that unlike the traditional @Efl.Io.Writer which will
|
||||
attempt to write directly and thus may take less data than
|
||||
requested, this one will keep the pending data in its own
|
||||
buffer, feeding to the actual output when it
|
||||
@Efl.Io.Writer.can_write. That makes its operation much simpler
|
||||
buffer, feeding to the actual output when
|
||||
@Efl.Io.Writer can write. That makes its operation much simpler
|
||||
as @Efl.Io.Writer.write will always take the full data -- allows
|
||||
"write and forget", if unlimited (see
|
||||
@.max_queue_size_output). When finished writing data, the
|
||||
@.eos_mark and then wait for "write,finished" event to know when all data
|
||||
was sent.
|
||||
@.max_queue_size_output). When finished writing data
|
||||
@.eos_mark then waits for the "write.finished" event to know all data
|
||||
has been sent.
|
||||
|
||||
Reading is also much simpler since incoming data is kept in an
|
||||
@Efl.Io.Queue, thus its size can be queried with @.pending_read
|
||||
and read with @Efl.Io.Reader.read or peeked with @.slice,
|
||||
then discarded with @.discard or @.clear.
|
||||
|
||||
Then when waiting for a complete message, just peek at its
|
||||
contents, if not complete do nothing and wait, if complete then
|
||||
either @Efl.Io.Reader.read to get a copy or manipulate a
|
||||
read-only reference from @.slice and then @.discard
|
||||
When waiting for a complete message, just peek at its
|
||||
contents, if not complete do nothing and wait. If complete then
|
||||
use either @Efl.Io.Reader.read to get a copy or manipulate a
|
||||
read-only reference from @.slice and then @.discard.
|
||||
|
||||
The actual I/O is set with the constructor method @.inner_io.set
|
||||
and can be retrieved with @.inner_io.get, which should be used
|
||||
|
@ -39,7 +39,7 @@ class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, E
|
|||
@property inner_io {
|
||||
[[The inner I/O this wrapper operates on.]]
|
||||
get {
|
||||
[[The internal input/output used for actual operations, use with care!]]
|
||||
[[The internal input/output used for actual operations. Use with care!]]
|
||||
}
|
||||
set {
|
||||
[[Constructor-only property to set the inner_io.]]
|
||||
|
@ -53,7 +53,7 @@ class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, E
|
|||
[[Limits how big the input queue can grow, in bytes.
|
||||
|
||||
If limited and @.line_delimiter is set, "line" events
|
||||
may be emitted with partial contents, without the
|
||||
may be emitted with partial contents without the
|
||||
trailing delimiter.
|
||||
]]
|
||||
get { }
|
||||
|
@ -61,30 +61,30 @@ class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, E
|
|||
[[Constructor-only property to set buffer limit. 0 is unlimited]]
|
||||
}
|
||||
values {
|
||||
max_queue_size_input: size; [[Defines a maximum buffer size for incoming data, or 0 to allow unlimited amount of bytes]]
|
||||
max_queue_size_input: size; [[Defines a maximum buffer size for incoming data or 0 to allow an unlimited amount of bytes]]
|
||||
}
|
||||
}
|
||||
|
||||
@property max_queue_size_output {
|
||||
[[Limits how big the output queue can grow, in bytes.
|
||||
[[Limits how big the output queue can grow in bytes.
|
||||
|
||||
|
||||
If limited, @Efl.Io.Writer.write will take less data than requested!
|
||||
If limited @Efl.Io.Writer.write will take less data than requested.
|
||||
]]
|
||||
get { }
|
||||
set {
|
||||
[[Constructor-only property to set buffer limit. 0 is unlimited]]
|
||||
}
|
||||
values {
|
||||
max_queue_size_output: size; [[Defines a maximum buffer size for output data, or 0 to allow unlimited amount of bytes. If limited, @Efl.Io.Writer.write will take less data than requested!]]
|
||||
max_queue_size_output: size; [[Defines a maximum buffer size for output data, or 0 to allow unlimited amount of bytes. If limited, @Efl.Io.Writer.write will take less data than requested.]]
|
||||
}
|
||||
}
|
||||
|
||||
@property line_delimiter {
|
||||
[[If set, incoming data will be checked for the delimiter and "line" events are The line may include the delimiter, unless it's end-of-stream on @.max_queue_size_input was reached.]]
|
||||
[[If set incoming data will be checked for the delimiter and "line" events. The line may include the delimiter, unless it's end-of-stream in @.max_queue_size_input has been reached.]]
|
||||
get { }
|
||||
set {
|
||||
[[Changes line delimiter to use. If empty, no delimiter is to be used]]
|
||||
[[Changes line delimiter to use. If empty no delimiter is to be used]]
|
||||
}
|
||||
values {
|
||||
slice: const(Eina.Slice); [[The contents may contain \0 and will be copied]]
|
||||
|
@ -102,7 +102,7 @@ class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, E
|
|||
greater-than zero. Defaults to inactive.
|
||||
]]
|
||||
values {
|
||||
seconds: double; [[Number inactive seconds to timeout this object. If zero or less, it will be disabled.]]
|
||||
seconds: double; [[Number of inactive seconds to timeout this object. If zero or less it will be disabled.]]
|
||||
}
|
||||
}
|
||||
|
||||
|
@ -110,13 +110,13 @@ class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, E
|
|||
[[Reads chunk size property, in bytes.
|
||||
|
||||
When reading the @.inner_io for data to be placed in
|
||||
input queue, use this as chunk size.
|
||||
input queue use this as chunk size.
|
||||
|
||||
Setting this value large enough may reduce number of
|
||||
@Efl.Io.Reader.read, improving performance at the expense
|
||||
of more memory consumption.
|
||||
|
||||
This value is bounded by @.max_queue_size_input if it's set.
|
||||
This value is limited by @.max_queue_size_input if it's set.
|
||||
|
||||
By default it's 4096.
|
||||
]]
|
||||
|
@ -160,7 +160,7 @@ class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, E
|
|||
|
||||
The memory pointed by slice may be changed by other
|
||||
methods of this class. The event "slice,changed" will be
|
||||
called in those situations.
|
||||
called in those circumstances.
|
||||
]]
|
||||
get { }
|
||||
values {
|
||||
|
@ -175,17 +175,17 @@ class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, E
|
|||
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
|
||||
It's often paired with @.slice. If users read the
|
||||
information from the slice, once they're done that
|
||||
data must be discarded.
|
||||
|
||||
As an example, some protocols provide messages with a
|
||||
"size" header, then @.slice is used to peek into the
|
||||
By way of example, some protocols provide messages with a
|
||||
"size" header. In that 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 this case the
|
||||
slice may be handled to some processing function. When
|
||||
the function is done, that amount of data must be
|
||||
discarded -- with this function.
|
||||
rest of the slice is the full payload. Here the
|
||||
slice may be handled by a processing function. When
|
||||
the function is complete, that amount of data must be
|
||||
discarded -- by this function.
|
||||
]]
|
||||
params {
|
||||
amount: size; [[Bytes to discard]]
|
||||
|
@ -195,17 +195,17 @@ class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, E
|
|||
clear {
|
||||
[[Clears the incoming queue. Same as reading all data.
|
||||
|
||||
This is equivalent as calling @.discard with @.pending_read
|
||||
This is equivalent to calling @.discard with @.pending_read
|
||||
amount of bytes.
|
||||
]]
|
||||
}
|
||||
|
||||
eos_mark {
|
||||
[[Marks this end-of-stream, signals nothing else will be written.
|
||||
[[Marks the end-of-stream. Signals nothing else will be written.
|
||||
|
||||
That will forbid any further writes.
|
||||
This will forbid any further writes.
|
||||
|
||||
Unlike @Efl.Io.Closer.close, this won't clear anything.
|
||||
Unlike @Efl.Io.Closer.close this won't clear anything.
|
||||
|
||||
When all data is written, "write,finished" is emitted.
|
||||
]]
|
||||
|
@ -217,14 +217,14 @@ class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, E
|
|||
It will return $true if @.pending_read drops to zero, $false
|
||||
otherwise and more calls to flush must be made.
|
||||
|
||||
If the @.inner_io is implements @Efl.Io.Closer and it
|
||||
was closed, or the wrapper itself was closed, this
|
||||
function will do nothing and returns $true.
|
||||
If the @.inner_io implements @Efl.Io.Closer and it
|
||||
is closed or the wrapper itself's closed, this
|
||||
function will do nothing and return $true.
|
||||
|
||||
\@note this function may block the main loop execution
|
||||
until operations complete! This is bad for usability, as
|
||||
user interface or other operations may freeze. A better
|
||||
approach is to operate asynchronously and wait for
|
||||
until operations are complete! This is bad for usability as
|
||||
the user interface or other operations may freeze. A better
|
||||
approach is to operate asynchronously and wait for the
|
||||
"write,finished" event.
|
||||
]]
|
||||
params {
|
||||
|
@ -239,10 +239,10 @@ class Efl.Io.Buffered_Stream (Efl.Loop.Consumer, Efl.Io.Reader, Efl.Io.Writer, E
|
|||
write,finished; [[@.eos_mark was called and all available data was sent to destination]]
|
||||
read,finished; [[Same as @Efl.Io.Reader "eos", for consistency.]]
|
||||
finished; [[Both read and write are finished.]]
|
||||
error: Eina.Error; [[An error happened and the I/O stopped]]
|
||||
error: Eina.Error; [[An error has occurred and I/O has stopped]]
|
||||
progress; [[Property @.progress changed]]
|
||||
slice,changed; [[The read-slice returned by @.slice may have changed.]]
|
||||
line: ptr(const(Eina.Slice)); [[If @.line_delimiter is set, will be emitted with current line. The memory is only valid during event callback dispatched and should not be modified. Note that the line slice may not be inside @.slice, don't assume that!]]
|
||||
line: ptr(const(Eina.Slice)); [[If @.line_delimiter is set, will be emitted with current line. The memory is only valid during event callback dispatched and should not be modified. Note that the line slice may not be inside @.slice.]]
|
||||
}
|
||||
|
||||
implements {
|
||||
|
|
|
@ -5,15 +5,15 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
|
||||
During usage it will keep reference to @.source and
|
||||
@.destination objects, automatically relasing them on
|
||||
destructor.
|
||||
destruction.
|
||||
|
||||
By default the read-write process is done based on fixed-size
|
||||
chunks (@.read_chunk_size), however if @.line_delimiter is set,
|
||||
the behavior changes to wait for such delimiter or a maximum
|
||||
chunks (@.read_chunk_size) but if @.line_delimiter is set,
|
||||
the behavior changes to wait for said delimiter or until a maximum
|
||||
buffer limit is reached (@.buffer_limit).
|
||||
|
||||
While a @.source is mandatory for the copier to operate
|
||||
properly, the @.destination is optional: if it's not provided,
|
||||
properly the @.destination is optional: if it's not provided,
|
||||
all read data is stored in an internal buffer that can be
|
||||
retrieved using @.binbuf_steal, usually called when one of
|
||||
"data", "line" or "done" events are emitted.
|
||||
|
@ -22,7 +22,7 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
|
||||
- The "data" event is general and notifies some data was
|
||||
written to @.destination (if any, otherwise it will be
|
||||
reported for data when it's read from @.source).
|
||||
reported as data when it's read from @.source).
|
||||
|
||||
- The "line" event is only emitted when @.line_delimiter is
|
||||
set and not empty. It's simiar to "data".
|
||||
|
@ -30,28 +30,28 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
- The "done" event is emitted if @.source is
|
||||
@Efl.Io.Reader.eos $true and all data was written to
|
||||
@.destination (if any, otherwise it will be reported when
|
||||
all data was read from @.source).
|
||||
all data is read from @.source).
|
||||
|
||||
- The "error" event is reported if the @Efl.Io.Reader.read,
|
||||
@Efl.Io.Writer.write or some other internal error happened,
|
||||
like out of memory. Another common error is ETIMEDOUT if
|
||||
@Efl.Io.Writer.write or some other internal error occurs,
|
||||
such as being out of memory. Another common error is ETIMEDOUT if
|
||||
@.timeout_inactivity is set.
|
||||
|
||||
A copier is handful to simplify common I/O use cases, such as:
|
||||
A copier is handy for simplifying common I/O use cases, such as:
|
||||
|
||||
- Read a file or download content to memory: provide only the
|
||||
- Reading a file or download content to memory: provide only the
|
||||
source and wait for "done" event, calling @.binbuf_steal
|
||||
afterwards.
|
||||
|
||||
- Download content to disk: provide a network socket as source
|
||||
- Downloading content to disk: provide a network socket as source
|
||||
and use @Efl.Io.File as destination, then wait for "done"
|
||||
event.
|
||||
|
||||
- Link two I/O streams: provide both source and destination
|
||||
- Linking two I/O streams: provide both source and destination
|
||||
streams, such as @Efl.Io.Stdin and @Efl.Io.Stdout, or some
|
||||
network socket. As data is received from source it will be
|
||||
copied to destination in an endless (asynchronous) loop. You
|
||||
may monitor for "done" if the source may be closed.
|
||||
may monitor for "done" if the source is closed.
|
||||
|
||||
If @Efl.Io.Closer.close is called, then it will be called on
|
||||
@.source and @.destination if they implement those interfaces.
|
||||
|
@ -72,12 +72,12 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
must be provided in order for the copier to work.
|
||||
|
||||
The copier will monitor @Efl.Io.Reader.can_read property
|
||||
and "can_read,changed" event. When it's $true, then a
|
||||
chunk up to @.read_chunk_size is read using
|
||||
and "can_read,changed" event. When $true a
|
||||
chunk (limited by @.read_chunk_size) is read using
|
||||
@Efl.Io.Reader.read into an intermediate storage buffer
|
||||
that can grow up to @.buffer_limit.
|
||||
which can grow up to the @.buffer_limit.
|
||||
|
||||
If there is a @.destination, the read data is written
|
||||
If there's a @.destination, the read data is written
|
||||
there and afterwards "data" and "line" events are
|
||||
dispatched. If no destination, it's accumulated in the
|
||||
internal storage and "data" and "line" events are
|
||||
|
@ -87,22 +87,22 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
that in order to attempt to write a full line at a time,
|
||||
including the delimiter. Exceptions may be if the
|
||||
@.source object emitted "eos" and there is no trailing
|
||||
delimiter (ie: missing trailing newline in files), or the
|
||||
@.buffer_limit was reached.
|
||||
delimiter (ie: missing trailing newline in files) or if the
|
||||
@.buffer_limit is reached.
|
||||
|
||||
Once @Efl.Io.Reader.eos is $true or "eos" event happen,
|
||||
then the read process is over. If there is no
|
||||
@.destination set, then the process is over and "done"
|
||||
event is called. If there is a @.destination, then all
|
||||
event is called. If there's a @.destination, then all
|
||||
data must be flushed to it, draining the internal
|
||||
intermediate storage, before "done" event is emitted.
|
||||
intermediate storage before "done" event is emitted.
|
||||
|
||||
If the source object implements @Efl.Io.Sizer interface,
|
||||
then the @.progress will report the total size. If the
|
||||
destination object also implements @Efl.Io.Sizer, then it
|
||||
will be resized to match the source size, providing the
|
||||
hint that may enhance performance (like pre-allocating
|
||||
the total amount and avoid dynamic resize).
|
||||
destination object also implements @Efl.Io.Sizer then it
|
||||
will be resized to match the source size/ It also offers
|
||||
hints to enhance performance such as pre-allocating
|
||||
the total amount and avoid dynamic resize.
|
||||
|
||||
If the source object implements @Efl.Io.Closer and it's
|
||||
not closed, it will be closed when the copier itself
|
||||
|
@ -131,7 +131,7 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
|
||||
If set it must implement @Efl.Io.Writer interface and
|
||||
will receive read data once @Efl.Io.Writer.can_write
|
||||
reports $true, this is monitored using
|
||||
reports $true, this is monitored using the
|
||||
"can_write,changed" event.
|
||||
|
||||
The copier will attempt to write all internal
|
||||
|
@ -139,29 +139,29 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
destination object may consume less. The actual data
|
||||
written is emitted in the "data" and "line" events.
|
||||
|
||||
If there is a @.line_delimiter set, then copier will use
|
||||
that in order to attempt to write a full line at a time,
|
||||
If there is an @.line_delimiter set then copier will use
|
||||
it in order to attempt to write one full line at a time,
|
||||
including the delimiter. Exceptions may be if the
|
||||
@.source object emitted "eos" and there is no trailing
|
||||
delimiter (ie: missing trailing newline in files), or the
|
||||
@.buffer_limit was reached.
|
||||
@.buffer_limit is reached.
|
||||
|
||||
If @.source is flagged "eos" and all data was written to
|
||||
destination, then "done" event is emitted.
|
||||
If @.source is flagged "eos" and all data is written to the
|
||||
destination then the "done" event is emitted.
|
||||
|
||||
If destination is not set (ie: NULL), then data is kept
|
||||
in a internal @Eina.Binbuf, that can be stolen with
|
||||
If the destination is not set (ie: NULL) then data is kept
|
||||
in a internal @Eina.Binbuf, which can be stolen with
|
||||
@.binbuf_steal once "data" or "line" events are
|
||||
emitted. It is allowed as a shortcut to easily drain
|
||||
readers and store all data in memory, not requiring an
|
||||
@Efl.Io.Buffer or @Efl.Io.Copier to be used -- a source
|
||||
and a copier are enough.
|
||||
emitted. It exists as a useful shortcut to easily drain
|
||||
readers and store all data in memory with no need to use an
|
||||
@Efl.Io.Buffer or @Efl.Io.Copier -- a source
|
||||
and copier are enough.
|
||||
|
||||
If both source and destination object implements
|
||||
@Efl.Io.Sizer, then destination will be resized to match
|
||||
the source size, providing the hint that may enhance
|
||||
performance (like pre-allocating the total amount and
|
||||
avoid dynamic resize).
|
||||
@Efl.Io.Sizer, then the destination will be resized to match
|
||||
the source size. It also offers hints to enhance
|
||||
performance such as pre-allocating the total amount and
|
||||
avoid dynamic resize.
|
||||
|
||||
If the destination object implements @Efl.Io.Closer and it's
|
||||
not closed, it will be closed when the copier itself
|
||||
|
@ -186,7 +186,7 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
}
|
||||
|
||||
@property line_delimiter {
|
||||
[[If there is a line delimiter, the reads will buffer/queue up to the line delimiter before calling @Efl.Io.Writer.write on the @.destination and the event line is emitted with current line. The line may include the delimiter, unless it's end-of-stream on @.source or @.buffer_limit was reached.]]
|
||||
[[If there is a line delimiter, reads will buffer/queue up to the line delimiter before calling @Efl.Io.Writer.write on the @.destination and the event line is emitted with the current line. The line may include the delimiter unless it's end-of-stream on @.source or @.buffer_limit was reached.]]
|
||||
get { }
|
||||
set {
|
||||
[[Changes line delimiter to use. If empty, no delimiter is to be used]]
|
||||
|
@ -200,17 +200,17 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
[[Copier buffer limit property, in bytes.
|
||||
|
||||
During the read-write cycle, an intermediate storage
|
||||
buffer is used. By default it's zero -- unlimited, and
|
||||
buffer is used. By default it's zero -- unlimited and
|
||||
will grow as needed if @.source provides data and
|
||||
@.destination do not consume it (or if there is no
|
||||
@.destination).
|
||||
|
||||
However when reading data from untrusted sources, like
|
||||
network, one can exhaust the system memory by flooding
|
||||
the copier. In such cases, using a buffer limit is
|
||||
However when reading data from untrusted sources like
|
||||
network system memory can be exhausted by flooding
|
||||
the copier. In these cases using a buffer limit is
|
||||
recommended.
|
||||
|
||||
When the buffer limit is reached, the copier will pause
|
||||
When the buffer limit is reached the copier will pause
|
||||
reading data from @.source until @.destination consumes
|
||||
it. If there is no @.destination set, user should call
|
||||
@.binbuf_steal to consume data and reset buffer usage.
|
||||
|
@ -273,8 +273,8 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
@property timeout_inactivity {
|
||||
[[Terminates the copier with ETIMEDOUT if it becomes inactive for some time.
|
||||
|
||||
If the copier cannot do any read or write in the given
|
||||
amount of seconds, then the copier will emit "error"
|
||||
If the copier cannot perform any reads or writes in the given
|
||||
amount of seconds then the copier will emit "error"
|
||||
event with ETIMEDOUT value.
|
||||
|
||||
This is specified in seconds and is only active for
|
||||
|
@ -289,7 +289,7 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
[[Reports if copier is done.
|
||||
|
||||
A copier is done if source reached "eos" and all data
|
||||
was written to "destination".
|
||||
is written to "destination".
|
||||
|
||||
The copier is also done when it's @Efl.Io.Closer.closed.
|
||||
]]
|
||||
|
@ -301,14 +301,14 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
}
|
||||
|
||||
binbuf_steal {
|
||||
[[Steals the internal binbuf and return it to caller.
|
||||
[[Steals the internal binbuf and returns it to caller.
|
||||
|
||||
The buffer is then owned by caller, which should call
|
||||
The buffer is then owned by caller which should call
|
||||
eina_binbuf_free() when it's done.
|
||||
|
||||
Usually call this method when no @.destination is set, in
|
||||
this case you should wait for "done", "data" or "line"
|
||||
events and then call it to retrieve (and own!) the data.
|
||||
which case you should wait for "done", "data" or "line"
|
||||
events and then call it to retrieve and own the data.
|
||||
]]
|
||||
return: ptr(Eina.Binbuf) @owned @warn_unused; [[Binbuf]]
|
||||
}
|
||||
|
@ -321,8 +321,8 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
@.destination, if any.
|
||||
|
||||
This is the equivalent of the size of returned by
|
||||
@.binbuf_steal, however it doesn't steal or modify the
|
||||
buffer at all, just query its internal size.
|
||||
@.binbuf_steal however it doesn't steal or modify the
|
||||
buffer at all, just queries its internal size.
|
||||
]]
|
||||
get { }
|
||||
values {
|
||||
|
@ -333,23 +333,23 @@ class Efl.Io.Copier (Efl.Loop.Consumer, Efl.Io.Closer) {
|
|||
flush {
|
||||
[[Forces reading from source and writing to destination.
|
||||
|
||||
This executes a single read->write cycle, if more data
|
||||
could be read from source (ie: not EOS) or not all data
|
||||
was written to destination, then $false is
|
||||
returned. Then to forcefully drain source and write all
|
||||
This executes a single read->write cycle if more data
|
||||
can be read from source (ie: not EOS) or not all data
|
||||
is written to destination, then $false is
|
||||
returned. To forcefully drain source and write all
|
||||
contents to destination, use in a loop until it returns
|
||||
$true.
|
||||
|
||||
The return value matches "done" event, that is, when
|
||||
The return value matches the "done" event: that is, when
|
||||
$true is returned, the "done" event is emitted.
|
||||
|
||||
This function may also emit "progress" and "error"
|
||||
events.
|
||||
|
||||
\@note this function may block the main loop execution
|
||||
until operations complete! This is bad for usability, as
|
||||
until operations are complete! This is bad for usability as
|
||||
user interface or other operations may freeze. A better
|
||||
approach is to operate asynchronously and wait for
|
||||
approach is to operate asynchronously and wait for the
|
||||
"done" event.
|
||||
]]
|
||||
params {
|
||||
|
|
|
@ -11,13 +11,13 @@ class Efl.Loop (Efl.Object)
|
|||
{
|
||||
[[The Efl Main Loop
|
||||
|
||||
Efl main loop provide a clean and tiny event loop library with many modules to
|
||||
do lots of convenient things for a programmer, to save time and effort. It's
|
||||
small and lean, designed to work from embedded systems all the way up to large
|
||||
and powerful multi-cpu workstations. The main loop has a number of primitives to
|
||||
be used with its main loop. It serializes all the primitives and allows for
|
||||
great responsiveness without the need for threads (or any other concurrency), but
|
||||
provide them if you need to.
|
||||
The Efl main loop provides a clean and tiny event loop library with many modules to
|
||||
do lots of convenient things for a programmer, saving time and effort. It's
|
||||
lean and designed to work on anything from embedded systems all the way up to large
|
||||
and powerful multi-cpu workstations. The main loop has a number of primitives you can use.
|
||||
It serializes these and allows for
|
||||
greater responsiveness without the need for threads (or any other concurrency). However
|
||||
you can provide these if you need to.
|
||||
]]
|
||||
methods {
|
||||
@property main @class {
|
||||
|
@ -80,7 +80,7 @@ class Efl.Loop (Efl.Object)
|
|||
return: ptr(Eina.Future) @owned /* TODO: future<void> */; [[The future handle.]]
|
||||
}
|
||||
@property throttle {
|
||||
[[Slow down the loop execution by forcing a sleep for a small
|
||||
[[Slow down the loop execution by forcing sleep for a small
|
||||
period of time every time the loop iterates/loops.]]
|
||||
set {}
|
||||
get {}
|
||||
|
@ -89,7 +89,7 @@ class Efl.Loop (Efl.Object)
|
|||
}
|
||||
}
|
||||
@property time {
|
||||
[[The time point when the loop was logically woken up.]]
|
||||
[[The time point when the loop was logically woken.]]
|
||||
set {}
|
||||
get {}
|
||||
values {
|
||||
|
@ -143,14 +143,14 @@ class Efl.Loop (Efl.Object)
|
|||
events {
|
||||
idle,enter @restart; [[Event occurs once the main loop enters the idle state.]]
|
||||
idle,exit @restart; [[Event occurs once the main loop exits the idle state.]]
|
||||
idle @restart; [[Event occurs once the main loop is idler. Be carefull, this will spin your CPU high if you keep listening on this event.]]
|
||||
idle @restart; [[Event occurs once the main loop is idle. If you keep listening on this event it may increase the burden on your CPU.]]
|
||||
arguments: Efl.Loop.Arguments; [[Event happens when args are provided to the loop by args_add().]]
|
||||
poll,high; [[Event occurs multiple time per second. The exact tick is undefined and could be adjusted system wide.]]
|
||||
poll,medium; [[Event occurs multiple time per minute. The exact tick is undefined and could be adjusted system wide.]]
|
||||
poll,low; [[Event occurs multiple time every 15 minutes. The exact tick is undefined and could be adjusted system wide.]]
|
||||
pause; [[Called when the window is going not be displayed for some time]]
|
||||
resume; [[Called before a window get rendered after a pause event]]
|
||||
terminate; [[Called before starting the shutdown of elementary]]
|
||||
poll,high; [[Event occurs multiple times per second. The exact tick is undefined and can be adjusted system wide.]]
|
||||
poll,medium; [[Event occurs multiple times per minute. The exact tick is undefined and can be adjusted system wide.]]
|
||||
poll,low; [[Event occurs multiple times every 15 minutes. The exact tick is undefined and can be adjusted system wide.]]
|
||||
pause; [[Called when the window is not going be displayed for some time]]
|
||||
resume; [[Called before a window is rendered after a pause event]]
|
||||
terminate; [[Called before starting the shutdown of Elementary]]
|
||||
}
|
||||
implements {
|
||||
Efl.Object.constructor;
|
||||
|
|
|
@ -1,8 +1,8 @@
|
|||
class Efl.Loop.Consumer (Efl.Object)
|
||||
{
|
||||
[[An Efl.Loop.Consumer is a class that require one of the parent to provide
|
||||
an Efl.Loop interface when doing provider_find. It will enforce this by
|
||||
only allowing parent that provide such interface or NULL.]]
|
||||
[[An Efl.Loop.Consumer is a class which requires one of the parents to provide
|
||||
an Efl.Loop interface when performing provider_find. It will enforce this by
|
||||
only allowing parents which provide such an interface or NULL.]]
|
||||
eo_prefix: efl_loop;
|
||||
methods {
|
||||
@property loop {
|
||||
|
|
|
@ -2,18 +2,18 @@ import eina_types;
|
|||
|
||||
class Efl.Loop.Fd (Efl.Loop.Consumer)
|
||||
{
|
||||
[[Fds are objects that what the activity on a given
|
||||
[[Fds are objects that watch the activity on a given
|
||||
file descriptor. This file descriptor can be a
|
||||
network, a file, provided by a library.
|
||||
|
||||
The object will trigger relevant event depending
|
||||
on what is happening.]]
|
||||
The object will trigger relevant events depending
|
||||
on what's happening.]]
|
||||
|
||||
methods {
|
||||
@property fd {
|
||||
[[Defines which file descriptor to watch. If it is a file, use file_fd variant.]]
|
||||
set {
|
||||
[[Defines the fd to watch on.]]
|
||||
[[Defines the fd to watch.]]
|
||||
}
|
||||
get {
|
||||
}
|
||||
|
|
|
@ -26,7 +26,7 @@ class Efl.Loop.Handler (Efl.Object)
|
|||
}
|
||||
}
|
||||
@property fd {
|
||||
[[ Controls a file desciptor to listen to for I/O that points
|
||||
[[ Controls a file desciptor to listen to for I/O, which points
|
||||
to a data pipe such as a device, socket or pipe etc. ]]
|
||||
set { }
|
||||
get { }
|
||||
|
@ -56,11 +56,11 @@ class Efl.Loop.Handler (Efl.Object)
|
|||
}
|
||||
}
|
||||
events {
|
||||
read; [[ Called when a read happened on the descriptor ]]
|
||||
write; [[ Called when a write happened on the descriptor ]]
|
||||
error; [[ Called when a error occurred on the descriptor ]]
|
||||
buffer; [[ Called when buffered data already read from the descriptor should be processed ]]
|
||||
prepare; [[ Called when preparing a descriptor for listening ]]
|
||||
read; [[ Called when a read occurs on the descriptor. ]]
|
||||
write; [[ Called when a write occurs on the descriptor. ]]
|
||||
error; [[ Called when a error occurrs on the descriptor. ]]
|
||||
buffer; [[ Called when buffered data already read from the descriptor should be processed. ]]
|
||||
prepare; [[ Called when preparing a descriptor for listening. ]]
|
||||
}
|
||||
|
||||
implements {
|
||||
|
|
|
@ -4,7 +4,7 @@ class Efl.Loop.Timer (Efl.Loop.Consumer)
|
|||
in the future and repeat that tick at a given interval.
|
||||
|
||||
Timers require the ecore main loop to be running and functioning
|
||||
properly. They do not guarantee exact timing, but try to work on a
|
||||
properly. They do not guarantee exact timing but try to work on a
|
||||
"best effort" basis.
|
||||
]]
|
||||
legacy_prefix: ecore_timer;
|
||||
|
@ -12,7 +12,7 @@ class Efl.Loop.Timer (Efl.Loop.Consumer)
|
|||
@property interval {
|
||||
[[Interval the timer ticks on.]]
|
||||
set {
|
||||
[[If set during a timer call, this will affect the next interval.]]
|
||||
[[If set during a timer call this will affect the next interval.]]
|
||||
}
|
||||
get {
|
||||
}
|
||||
|
@ -40,16 +40,16 @@ class Efl.Loop.Timer (Efl.Loop.Consumer)
|
|||
]]
|
||||
}
|
||||
loop_reset {
|
||||
[[This effectively reset a timer, but based on the time when this iteration of the main loop started.
|
||||
[[This effectively resets a timer but based on the time when this iteration of the main loop started.
|
||||
@since 1.18
|
||||
]]
|
||||
}
|
||||
delay {
|
||||
[[Adds some delay for the next occurrence of a timer.
|
||||
This doesn't affect the interval of a timer.
|
||||
[[Adds a delay to the next occurrence of a timer.
|
||||
This doesn't affect the timer interval.
|
||||
]]
|
||||
params {
|
||||
@in add: double; [[The amount of time to delay the timer by in seconds]]
|
||||
@in add: double; [[The amount of time by which to delay the timer in seconds]]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
@ -68,9 +68,9 @@ class Efl.Loop.Timer (Efl.Loop.Consumer)
|
|||
* @param timer The timer to be paused.
|
||||
*
|
||||
* The timer callback won't be called while the timer is paused. The remaining
|
||||
* time until the timer expires will be saved, so the timer can be resumed with
|
||||
* time until the timer expires will be saved so the timer can be resumed with
|
||||
* that same remaining time to expire, instead of expiring instantly. Use
|
||||
* ecore_timer_thaw() to resume it.
|
||||
* ecore_timer_thaw() to resume.
|
||||
*
|
||||
* @note Nothing happens if the timer was already paused.
|
||||
*
|
||||
|
@ -83,10 +83,10 @@ class Efl.Loop.Timer (Efl.Loop.Consumer)
|
|||
*
|
||||
* @param timer The timer to be resumed.
|
||||
*
|
||||
* The timer will be resumed from its previous relative position in time. That
|
||||
* means, if it had X seconds remaining until expire when it was paused, it will
|
||||
* be started now with those same X seconds remaining to expire again. But
|
||||
* notice that the interval time won't be touched by this call or by
|
||||
* The timer will be resumed from its previous relative position. This
|
||||
* means if it had X seconds remaining until expiry when paused, it will
|
||||
* now start with those same X seconds remaining.
|
||||
* The interval time won't be affected by this call nor by
|
||||
* ecore_timer_freeze().
|
||||
*
|
||||
* @see ecore_timer_freeze()
|
||||
|
|
|
@ -5,13 +5,13 @@ class Efl.Model.Container (Efl.Object, Efl.Model)
|
|||
[[
|
||||
Class used to create data models from Eina containers.
|
||||
|
||||
Each container supplied represent a series of property values, each item
|
||||
Each container supplied represents a series of property values, each item
|
||||
being the property value for a child object (@Efl.Model.Container.Item).
|
||||
|
||||
The data in the given containers are copied and stored internally.
|
||||
|
||||
Several containers can be supplied, and the number of allocated children is
|
||||
based on the container with the biggest size.
|
||||
Several containers can be supplied and the number of allocated children is
|
||||
based on the container of the largest size.
|
||||
]]
|
||||
methods {
|
||||
child_property_value_type_get {
|
||||
|
|
|
@ -5,9 +5,9 @@ class Efl.Promise (Efl.Loop.Consumer)
|
|||
[[Efl promise class]]
|
||||
methods {
|
||||
progress_set {
|
||||
[[Updates the progress and send it immediately to all connected Efl_Future.
|
||||
[[Updates progress and sends it immediately to all connected Efl_Future.
|
||||
|
||||
The progress is not kept and when the function return it will not be accessed
|
||||
The progress is not stored and when the function returns it will not be accessed
|
||||
anymore. The pointer is owned by the caller and will remain so after the return
|
||||
of the function call.
|
||||
]]
|
||||
|
@ -18,23 +18,24 @@ class Efl.Promise (Efl.Loop.Consumer)
|
|||
@property future {
|
||||
[[Requests a new future linked to this promise.
|
||||
|
||||
Efl_Future are optional and will be automatically deleted if no then callback have
|
||||
Efl_Future are optional and will be automatically deleted if no callbacks have
|
||||
been set before the next iteration of the main loop.
|
||||
]]
|
||||
get {
|
||||
[[The returned new future.]]
|
||||
}
|
||||
values {
|
||||
f: future<void_ptr, void_ptr>; [[Returns a future where the value will be set by calling value_set while the progress will be updated by progress_set.]]
|
||||
f: future<void_ptr, void_ptr>; [[Returns a future where the value will be set by calling value_set whilst the progress is
|
||||
updated by progress_set.]]
|
||||
}
|
||||
}
|
||||
@property value {
|
||||
[[The value expected by all connected future.]]
|
||||
set {
|
||||
[[
|
||||
This function can be called only once and you can not call #failed.set after that.
|
||||
The value will be owned by the promise until it is destroyed. The value will be cleaned
|
||||
when the promise and all the future depending on it are destroyed.
|
||||
This function can be called only once. You cannot call #failed.set after doing so.
|
||||
The value will be owned by the promise until it's destroyed. It will be cleaned
|
||||
when the promise and all futures depending on it are destroyed.
|
||||
]]
|
||||
}
|
||||
values {
|
||||
|
@ -46,7 +47,7 @@ class Efl.Promise (Efl.Loop.Consumer)
|
|||
[[Defines the failure state of this promise.]]
|
||||
set {
|
||||
[[
|
||||
This function can be called only once and you can not call #value.set after that.
|
||||
This function can be called only once and you cannot call #value.set after doing so.
|
||||
]]
|
||||
}
|
||||
values {
|
||||
|
@ -57,18 +58,19 @@ class Efl.Promise (Efl.Loop.Consumer)
|
|||
[[Connects a future output to this promise.
|
||||
|
||||
This helper will automatically trigger #value.set or #failed.set when the future
|
||||
succeed or fail respectively with the value provided by the future.
|
||||
succeeds or fails respectively, with the value provided by the future.
|
||||
]]
|
||||
params {
|
||||
@in f: future<void_ptr, void_ptr>; [[The future to connect this promise to.]]
|
||||
@in f: future<void_ptr, void_ptr>; [[The future to connect to this promise.]]
|
||||
}
|
||||
return: bool; [[Returns $false if unable to setup the connection.]]
|
||||
return: bool; [[Returns $false if unable to set up the connection.]]
|
||||
}
|
||||
}
|
||||
events {
|
||||
future,set: future<void_ptr>; [[This event is triggered whenever a future is fully set to receive all events and that the user of it do not hold any more reference on it.]]
|
||||
future,progress,set: future<void_ptr>; [[This event is triggered whenever a future has a progress callback registered and the user does not hold any more reference on it.]]
|
||||
future,none; [[This event is triggered whenever there is no more future connected to the promise.]]
|
||||
future,set: future<void_ptr>; [[This event is triggered whenever a future is fully set to receive all events and the user
|
||||
holds no more references to it.]]
|
||||
future,progress,set: future<void_ptr>; [[This event is triggered whenever a future has a progress callback registered and the user holds no more reference to it.]]
|
||||
future,none; [[This event is triggered whenever there are no more futures connected to the promise.]]
|
||||
}
|
||||
implements {
|
||||
Efl.Object.destructor;
|
||||
|
|
Loading…
Reference in New Issue