Copier is based on Efl.Io.Reader.can_read,changed and
Efl.Io.Writer.can_write,changed, these events do not keep being posted
until it's actually read/written, instead they trigger only once when
the property change -- unlike Efl.Loop_Fd read/write events.
Working directly with Eina_Slice is easier than a pointer to it,
requires no validation of the pointers and is cheap since it's just
putting together size_t + void*.
However we can't hint the user of 'const(Eina.Slice)' properties as
Eolian is incorrectly generating getters as:
const Eina_Slice class_property_get(...)
which is makes compilers complain about ignored qualifiers:
../src/lib/ecore/efl_io_copier.eo.h:329:7: warning: 'const' type qualifier on return type has no effect [-Wignored-qualifiers]
Leave some TODO so @q66 can fix those.
In some cases the copier isn't done but you know there is not more
data to arrive at it, then you want to know if all pending data was
flushed from the copier's intermediate buffer to the destination, if
so you can call it closed yourself.
The may_block parameter is useful to force a flush without blocking on
read/write, sometimes particularly useful if ignore_line_delimiter is
true, then you get the data events without blocking -- as if a server
sending some content misses a trailing line delimiter, you do not want
to block on recv() but still want to flush data to user.
The ignore_line_delimiter parameter is useful if we're going to close
the copier and want to flush pending data which may exist due missing
trailing terminator. The close method will also force that if
destination can take more data.
This method will force a read-write cycle and returns if it's fully
done or not. It may be used to force data to be written before a
handle is deleted (when one can't wait for the data to be written
asynchronously).
As done by write, if we try to read and we can't, then don't give
up. This happens with streams that wraps another, like SSL, may report
there are data to read, but once you try it may not result in enough
data to upper layers.
The pointer given to efl_future_use() should be NULL-ified before
calling my function, since that pointer has no meaning anymore.
The copier relied on pd->job being NULL to avoid useless rescheduling,
it was being reached with non-null, but that pointer is no longer
useful.
Moreover, I'm not sure if the second pointer, with the new future
won't be modified to NULL when the efl_future continues :-(
This is handful to error the copier with ETIMEDOUT if there are no
reads or writes in the given amount of time.
Since copiers are usable to download data or handle network clients,
it's easy to set a timeout and disconnect, let's say UDP clients that
are gone.
Efl_Future actually work with weak reference. So you do not need to
set things to NULL, but you actually need to register the memory location
of the future with efl_future_use.
while in a job we do not have the safety of eo holding us alive and
when we call back the user, he may have deleted the object, releasing
both the object and its private data that we're using.
then keep an extra reference, call the methods and release it.
Efl.Object.event_callback_call no longer calls legacy smart callbacks;
calling only event callbacks registered with the given event description
pointer.
Create the method Efl.Object.event_callback_legacy_call to inherit the old
behavior from Efl.Object.event_callback_call, calling both Efl.Object events
and legacy smart callbacks.
Update all other files accordingly in order to still supply legacy
callbacks while they are necessary.
These interfaces allows generic operations on objects that can store
or provide data, such as a file or a buffer.
With well defined interfaces and events we can create code such as
Efl.Io.Copier, that will link a source with a destination and
progressively copy data as they appear.
Gustavo Sverzut Barbieri
Jean-Philippe Andre
Cedric BAIL
Vitor Sousa
Tom Hacohen