Efl.Io.Copier (class)

Description

Copy from an Efl.Io.Reader source to Efl.Io.Writer destination.

During usage it will keep reference to Efl.Io.Copier.source and Efl.Io.Copier.destination objects, automatically relasing them on destruction.

By default the read-write process is done based on fixed-size chunks (Efl.Io.Copier.read_chunk_size) but if Efl.Io.Copier.line_delimiter is set, the behavior changes to wait for said delimiter or until a maximum buffer limit is reached (Efl.Io.Copier.buffer_limit).

While a Efl.Io.Copier.source is mandatory for the copier to operate properly the Efl.Io.Copier.destination is optional: if it's not provided, all read data is stored in an internal buffer that can be retrieved using Efl.Io.Copier.binbuf_steal, usually called when one of "data", "line" or "done" events are emitted.

Most important events:

- The "data" event is general and notifies some data was written to Efl.Io.Copier.destination (if any, otherwise it will be reported as data when it's read from Efl.Io.Copier.source).

- The "line" event is only emitted when Efl.Io.Copier.line_delimiter is set and not empty. It's simiar to "data".

- The "done" event is emitted if Efl.Io.Copier.source is Efl.Io.Reader.eos true and all data was written to Efl.Io.Copier.destination (if any, otherwise it will be reported when all data is read from Efl.Io.Copier.source).

- The "error" event is reported if the Efl.Io.Reader.read, Efl.Io.Writer.write or some other internal error occurs, such as being out of memory. Another common error is ETIMEDOUT if Efl.Io.Copier.timeout_inactivity is set.

A copier is handy for simplifying common I/O use cases, such as:

- Reading a file or download content to memory: provide only the source and wait for "done" event, calling Efl.Io.Copier.binbuf_steal afterwards.

- Downloading content to disk: provide a network socket as source and use Efl.Io.File as destination, then wait for "done" event.

- 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 is closed.

If Efl.Io.Closer.close is called, then it will be called on Efl.Io.Copier.source and Efl.Io.Copier.destination if they implement those interfaces.

Efl.Io.Closer.close_on_exec and Efl.Io.Closer.close_on_destructor are respected and applied to both source and destination. Both default to true.

Since 1.19

Inheritance

Members

binbuf_steal

Steals the internal binbuf and returns it to caller.
Eina_Binbuf *efl_io_copier_binbuf_steal(Eo *obj);


buffer_limit (get, set)

Copier buffer limit property, in bytes.
size_t efl_io_copier_buffer_limit_get(const Eo *obj);
void efl_io_copier_buffer_limit_set(Eo *obj, size_t size);


close [Overridden from Efl.Io.Closer]

Closes the Input/Output object.
Eina_Error efl_io_closer_close(Eo *obj);


close_on_destructor (get, set) [Overridden from Efl.Io.Closer]

If true will automatically close() on object destructor.
Eina_Bool efl_io_closer_close_on_destructor_get(const Eo *obj);
void efl_io_closer_close_on_destructor_set(Eo *obj, Eina_Bool close_on_destructor);


close_on_exec (get, set) [Overridden from Efl.Io.Closer]

If true will automatically close resources on exec() calls.
Eina_Bool efl_io_closer_close_on_exec_get(const Eo *obj);
Eina_Bool efl_io_closer_close_on_exec_set(Eo *obj, Eina_Bool close_on_exec);


closed (get, set) [Overridden from Efl.Io.Closer]

If true will notify object was closed.
Eina_Bool efl_io_closer_closed_get(const Eo *obj);
Eina_Bool efl_io_closer_closed_set(Eo *obj, Eina_Bool is_closed);


constructor [Overridden from Efl.Object]

Call the object's constructor.
Efl_Object *efl_constructor(Eo *obj);


destination (get, set)

Copier destination object.
Efl_Io_Writer *efl_io_copier_destination_get(const Eo *obj);
void efl_io_copier_destination_set(Eo *obj, Efl_Io_Writer *destination);


destructor [Overridden from Efl.Object]

Call the object's destructor.
void efl_destructor(Eo *obj);


done (get, set) protected set

Reports if copier is done.
Eina_Bool efl_io_copier_done_get(const Eo *obj);
void efl_io_copier_done_set(Eo *obj, Eina_Bool done);


finalize [Overridden from Efl.Object]

Called at the end of efl_add. Should not be called, just overridden.
Efl_Object *efl_finalize(Eo *obj);


flush

Forces reading from source and writing to destination.
Eina_Bool efl_io_copier_flush(Eo *obj, Eina_Bool may_block, Eina_Bool ignore_line_delimiter);


line_delimiter (get, set)

If there is a line delimiter, reads will buffer/queue up to the line delimiter before calling Efl.Io.Writer.write on the Efl.Io.Copier.destination and the event line is emitted with the current line. The line may include the delimiter unless it's end-of-stream on Efl.Io.Copier.source or Efl.Io.Copier.buffer_limit was reached.
const Eina_Slice efl_io_copier_line_delimiter_get(const Eo *obj);
void efl_io_copier_line_delimiter_set(Eo *obj, const Eina_Slice slice);


pending_size (get)

Returns the size of the pending buffer.
size_t efl_io_copier_pending_size_get(const Eo *obj);


progress (get)

Progress for read and write.
void efl_io_copier_progress_get(const Eo *obj, uint64_t *read, uint64_t *written, uint64_t *total);


read_chunk_size (get, set)

Copier read chunk size property, in bytes.
size_t efl_io_copier_read_chunk_size_get(const Eo *obj);
void efl_io_copier_read_chunk_size_set(Eo *obj, size_t size);


source (get, set)

Copier source object.
Efl_Io_Reader *efl_io_copier_source_get(const Eo *obj);
void efl_io_copier_source_set(Eo *obj, Efl_Io_Reader *source);


timeout_inactivity (get, set)

Terminates the copier with ETIMEDOUT if it becomes inactive for some time.
double efl_io_copier_timeout_inactivity_get(const Eo *obj);
void efl_io_copier_timeout_inactivity_set(Eo *obj, double seconds);


Inherited

Efl.Loop.Consumer
loop (get) The loop to which this object belongs to.
parent (get, set) The parent of an object.
Efl.Object
allow_parent_unref (get, set) Allow an object to be deleted by unref even if it has a parent.
children_iterator_new Get an iterator on all childrens
comment (get, set) A human readable comment for the object
composite_attach Make an object a composite object of another.
composite_detach Detach a composite object from another object.
composite_part_is Check if an object is part of a composite object.
debug_name_override Build a read-only name for this object used for debugging.
del Unrefs the object and reparents it to NULL.
event_callback_forwarder_add Add an event callback forwarder for an event and an object.
event_callback_forwarder_del Remove an event callback forwarder for an event and an object.
event_callback_stop Stop the current callback call.
event_freeze Freeze events of object.
event_freeze_count (get) Return freeze events of object.
class event_global_freeze Freeze events of object.
class event_global_freeze_count (get) Return freeze events of object.
class event_global_thaw Thaw events of object.
event_thaw Thaw events of object.
finalized (get) True if the object is already finalized, otherwise false.
name (get, set) The name of the object.
name_find Find a child object with the given name and return it.
provider_find Searches upwards in the object tree for a provider which knows the given class/interface.

Events

data

When data is read to internal buffer, it's emitted in this event. The memory is only valid during event callback dispatched and should not be modified.
EFL_IO_COPIER_EVENT_DATA(const Eina_Slice *)


done

All available data was copied from source to destination
EFL_IO_COPIER_EVENT_DONE(void)


error

An error happened and the copy stopped
EFL_IO_COPIER_EVENT_ERROR(Eina_Error)


line

If Efl.Io.Copier.line_delimiter is set, will be emitted with current line. The memory is only valid during event callback dispatched and should not be modified.
EFL_IO_COPIER_EVENT_LINE(const Eina_Slice *)


progress

Total size changed or Data was read/written
EFL_IO_COPIER_EVENT_PROGRESS(void)


Inherited

Efl.Io.Closer
closed Notifies closed, when property is marked as true
Efl.Object
callback,add A callback was added.
callback,del A callback was deleted.
del Object is being deleted.
destruct Object has been fully destroyed. It can not be used beyond this point. This event should only serve to clean up any dangling pointer.