WWW-www.enlightenment.org pushed a commit to branch master.
http://git.enlightenment.org/website/www-content.git/commit/?id=58b859f7fbd3c4eb1afe2140f8b77a84d9f8174b
commit 58b859f7fbd3c4eb1afe2140f8b77a84d9f8174b
Author: Nate Drake <nate.dr...@gmx.com>
Date: Wed Dec 20 07:57:44 2017 -0800
Wiki page io.md changed with summary [] by Nate Drake
---
pages/develop/guides/c/core/io.md.txt | 65 +++++++++++++++++------------------
1 file changed, 32 insertions(+), 33 deletions(-)
diff --git a/pages/develop/guides/c/core/io.md.txt
b/pages/develop/guides/c/core/io.md.txt
index fb8359aa4..d3a305df1 100644
--- a/pages/develop/guides/c/core/io.md.txt
+++ b/pages/develop/guides/c/core/io.md.txt
@@ -51,9 +51,9 @@ In juxtaposition to ``Efl.Io.Reader``, this interface
provides a method to write
### ``Efl.Io.Closer`` ###
-Read the whole documentation in the ``Efl.Io.Closer`` [API Reference
guide](/develop/api/efl/io/closer).
+Read the entire documentation in ``Efl.Io.Closer`` [API Reference
guide](/develop/api/efl/io/closer).
-This interface provides a method to close a stream (be it an input or output
stream) and convenience properties to close it automatically.
+This interface provides a method to close a stream (be it an input or output
stream) and convenient properties to close it automatically.
* ``efl_io_closer_close()`` method: Closes the stream, deallocating all
related resources.
@@ -67,7 +67,7 @@ This interface provides a method to close a stream (be it an
input or output str
### ``Efl.Io.Positioner`` ###
-Read the whole documentation in the ``Efl.Io.Positioner`` [API Reference
guide](/develop/api/efl/io/positioner).
+Read the entire documentation in ``Efl.Io.Positioner`` [API Reference
guide](/develop/api/efl/io/positioner).
This interface provides methods, properties and events to track the current
position inside a data stream.
@@ -79,11 +79,11 @@ This interface provides methods, properties and events to
track the current posi
### ``Efl.Io.Sizer`` ###
-Read the whole documentation in the ``Efl.Io.Sizer`` [API Reference
guide](/develop/api/efl/io/sizer).
+Read the entire documentation in ``Efl.Io.Sizer`` [API Reference
guide](/develop/api/efl/io/sizer).
This interface provides methods, properties and events to track the size of a
data stream.
-* ``efl_io_sizer_resize()`` method: changes the size of the stream. Useful for
files, for example.
+* ``efl_io_sizer_resize()`` method: changes the size of the stream. This is
useful for files, for instance.
* ``efl_io_sizer_size_get()`` property: returns the current size of the stream.
@@ -91,15 +91,15 @@ This interface provides methods, properties and events to
track the size of a da
## Classes ##
-This sections details a set of classes which you can instantiate to perform
miscellaneous I/O tasks, and the interfaces they implement. You can use the
interface methods listed above on the classes that support them. The most
relevant class-specific methods are given below, but for a complete list of
methods, use the [API Reference guide](/develop/api/) (A direct link to the
appropriate page is given for each class).
+This sections details a set of classes which you can instantiate to perform
miscellaneous I/O tasks and the interfaces they implement. You can use the
interface methods listed above on the classes that support them. The most
relevant class-specific methods are given below but for a complete list of
methods use the [API Reference guide](/develop/api/). A direct link to the
appropriate page is given for each class.
### ``Efl.Io.File`` ###
-Read the whole documentation in the ``Efl.Io.File`` [API Reference
guide](/develop/api/efl/io/file). It implements the ``Efl.Io.Reader``,
``Efl.Io.Writer``, ``Efl.Io.Closer``, ``Efl.Io.Positioner`` and
``Efl.Io.Sizer`` interfaces.
+Read the entire documentation in ``Efl.Io.File`` [API Reference
guide](/develop/api/efl/io/file). It implements the ``Efl.Io.Reader``,
``Efl.Io.Writer``, ``Efl.Io.Closer``, ``Efl.Io.Positioner`` and
``Efl.Io.Sizer`` interfaces.
-You use this object in a similar way as you use a plain ``FILE *`` in C. You
create it, give it a filename, perform some read or write operations, and then
destroy the object.
+You can use this object in a similar way as you would a plain ``FILE *`` in C
in that you create it, give it a filename, perform some read or write
operations and then destroy the object.
-Here's an example extracted from the EFL examples repository:
[reference/c/core/src/core_io.c](https://git.enlightenment.org/tools/examples.git/tree/reference/c/core/src/core_io.c)
+Here's an example from the EFL examples repository:
[reference/c/core/src/core_io.c](https://git.enlightenment.org/tools/examples.git/tree/reference/c/core/src/core_io.c)
```c
Eina_Slice content = EINA_SLICE_STR("### This is a sample string for the
file io test ###");
@@ -125,13 +125,13 @@ Here's an example extracted from the EFL examples
repository: [reference/c/core/
### ``Efl.Io.Queue`` ###
-Read the whole documentation in the ``Efl.Io.Queue`` [API Reference
guide](/develop/api/efl/io/queue). It implements the ``Efl.Io.Reader``,
``Efl.Io.Writer`` and ``Efl.Io.Closer`` interfaces.
+Read the entire documentation in ``Efl.Io.Queue`` [API Reference
guide](/develop/api/efl/io/queue). It implements the ``Efl.Io.Reader``,
``Efl.Io.Writer`` and ``Efl.Io.Closer`` interfaces.
This is a *first-in first-out* (FIFO) memory queue where data can be enqueued
using the ``Efl.Io.Writer`` interface and dequeued using the ``Efl.Io.Reader``
interface.
-It is convenient, for example, to decouple two processes, as reads and writes
can happen independently, and the queue automatically shrinks and grows to
adapt to its content.
+It's convenient, for example, to decouple two processes as reads and writes
can happen independently. The queue automatically shrinks and grows to adapt to
its content.
-It's maximum size can be bounded through the ``limit`` property. Writes to a
full queue and reads from an empty queue will both fail.
+Its maximum size can be bounded through the ``limit`` property. Any attempted
writes to a full queue or reads from an empty queue will fail.
The most representative methods of the ``Efl.Io.Queue`` are:
@@ -163,13 +163,13 @@ More usage examples can be found in the EFL examples
repository: [reference/c/ne
### ``Efl.Io.Buffer`` ###
-Read the whole documentation in the ``Efl.Io.Buffer`` [API Reference
guide](/develop/api/efl/io/buffer). It implements the ``Efl.Io.Reader``,
``Efl.Io.Writer``, ``Efl.Io.Closer``, ``Efl.Io.Positioner`` and
``Efl.Io.Sizer`` interfaces.
+Read the entire documentation in the ``Efl.Io.Buffer`` [API Reference
guide](/develop/api/efl/io/buffer). It implements the ``Efl.Io.Reader``,
``Efl.Io.Writer``, ``Efl.Io.Closer``, ``Efl.Io.Positioner`` and
``Efl.Io.Sizer`` interfaces.
-Buffers are similar to Queues in that they act as in-memory storage for data,
but they allow independent handling of the read and write pointers, effectively
providing complete access to the whole memory block.
+Buffers are similar to Queues in that they act as in-memory storage for data
but they allow independent handling of the read and write pointers. This
effectively provides complete access to the whole memory block.
-If only the ``Efl.Io.Reader`` and ``Efl.Io.Writer`` interfaces are used, it
acts as a FIFO, exactly like ``Efl.Io.Queue``. Random access to any portion of
the memory block, though, can be gained through the ``position_read`` and
``position_write`` properties, which move the read and write pointers
independently.
+If only the ``Efl.Io.Reader`` and ``Efl.Io.Writer`` interfaces are used, it
acts as a FIFO exactly like ``Efl.Io.Queue``. Random access to any portion of
the memory block can be gained however through the ``position_read`` and
``position_write`` properties, which move the read and write pointers
independently.
-It's maximum size can be bounded through the ``limit`` property. Writes to a
full queue and reads from an empty queue will both fail.
+Its maximum size can be set through the ``limit`` property. Attempted writes
to a full queue or reads from an empty queue will fail.
The most representative methods of the ``Efl.Io.Buffer`` are:
@@ -181,27 +181,27 @@ The most representative methods of the ``Efl.Io.Buffer``
are:
### ``Efl.Io.Copier`` ###
-Read the whole documentation in the ``Efl.Io.Copier`` [API Reference
guide](/develop/api/efl/io/copier). It implements the ``Efl.Io.Closer``
interface.
+Read the entire documentation in the ``Efl.Io.Copier`` [API Reference
guide](/develop/api/efl/io/copier). It implements the ``Efl.Io.Closer``
interface.
-This is a convenience object that will copy data asynchronously from any
source object implementing the ``Efl.Io.Reader`` interface into any destination
object implementing the ``Efl.Io.Writer`` interface until the End-of-Stream
event is received or an error occurs.
+This is a convenient object which copies data asynchronously from any source
object implementing the ``Efl.Io.Reader`` interface into any destination object
implementing the ``Efl.Io.Writer`` interface until the End-of-Stream event is
received or an error occurs.
-Usage scenarios include downloading a URL to memory or to a file, copy files
around the hard drive or copy data from/to any file descriptor.
+Usage scenarios include downloading a URL to memory or to a file, copying
files around the hard drive or copying data from/to any file descriptor.
-To use the ``Efl.Io.Copier`` class, you only need to instantiate it, set the
``source`` and ``destination`` properties and register to receive the
``EVENT_DONE`` or ``EVENT_ERROR`` callbacks.
+To use the ``Efl.Io.Copier`` class you only need to instantiate it. Next set
the ``source`` and ``destination`` properties then register to receive the
``EVENT_DONE`` or ``EVENT_ERROR`` callbacks.
Data can be copied in blocks of fixed size (controlled through the
``read_chunk_size`` property) or of variable size, using a delimiter
(configured through the ``line_delimiter`` property).
The most representative methods of ``Efl.Io.Copier`` are:
-* ``efl_io_copier_source_get/set()`` sets the source object, which must
implement the ``Efl.Io.Reader`` interface.
+* ``efl_io_copier_source_get/set()`` sets the source object which must
implement the ``Efl.Io.Reader`` interface.
-* ``efl_io_copier_destination_get/set()`` sets the destination object, which
must implement the ``Efl.Io.Writer`` interface.
+* ``efl_io_copier_destination_get/set()`` sets the destination object which
must implement the ``Efl.Io.Writer`` interface.
-* ``efl_io_copier_done_get()`` returns ``TRUE`` when the copy has finished.
Better use the ``EFL_IO_COPIER_EVENT_DONE`` event for asynchronous operation.
+* ``efl_io_copier_done_get()`` returns ``TRUE`` when the copy has finished.
Use the ``EFL_IO_COPIER_EVENT_DONE`` event for asynchronous operation.
* ``efl_io_copier_line_delimiter_get/set()`` sets the delimiter to use.
-* ``efl_io_copier_progress_get()`` returns the amount of bytes read and
written, and the total, if known. Better use the
``EFL_IO_COPIER_EVENT_PROGRESS`` for asynchronous operation.
+* ``efl_io_copier_progress_get()`` returns the amount of bytes read and
written and the total, if known. Use the ``EFL_IO_COPIER_EVENT_PROGRESS`` for
asynchronous operation.
* ``efl_io_copier_read_chunk_size_get/set()`` sets the amount of bytes to
fetch in each read operation, if no delimiter is being used.
@@ -217,7 +217,7 @@ The most representative methods of ``Efl.Io.Copier`` are:
* ``EFL_IO_COPIER_EVENT_PROGRESS`` is emitted when the amount of bytes read,
written or total changes.
-Here's an usage example extracted from the EFL examples repository,
[reference/c/core/src/core_io.c](https://git.enlightenment.org/tools/examples.git/tree/reference/c/core/src/core_io.c).
It copies data from *stdin* to *stdout* until ``Ctrl+D`` is pressed.
+Here's an usage example extracted from the EFL examples repository
[reference/c/core/src/core_io.c](https://git.enlightenment.org/tools/examples.git/tree/reference/c/core/src/core_io.c).
It copies data from *stdin* to *stdout* until ``Ctrl+D`` is pressed:
```c
EFL_CALLBACKS_ARRAY_DEFINE(copier_cbs,
@@ -242,22 +242,21 @@ EFL_CALLBACKS_ARRAY_DEFINE(copier_cbs,
efl_event_callback_array_add(efl_added, copier_cbs(),
NULL));
```
-To understand how the different events are registered through a single
callback array, read the [Events Programming
Guide](/develop/guides/c/core/events.md).
+To discover how different events are registered through a single callback
array read the [Events Programming Guide](/develop/guides/c/core/events.md).
-A more complex usage example can be found in the EFL examples repository:
-[reference/c/net/src/net_io.c](https://git.enlightenment.org/tools/examples.git/tree/reference/c/net/src/net_io.c).
It sends commands to an HTTP server using an ``Efl.Io.Copier`` that reads from
an ``Efl.Io.Queue`` and then receives the answers using a second
``Efl.Io.Copier`` and another ``Efl.Io.Queue``. This example is detailed in the
[Network Programming Guide](/develop/guides/c/core/net.md).
+A more complex usage example can be found in the EFL examples repository
[reference/c/net/src/net_io.c](https://git.enlightenment.org/tools/examples.git/tree/reference/c/net/src/net_io.c).
It sends commands to an HTTP server using an ``Efl.Io.Copier`` which reads
from an ``Efl.Io.Queue``. It then receives answers using a second
``Efl.Io.Copier`` and another ``Efl.Io.Queue``. This example is detailed in the
[Network Programming Guide](/develop/guides/c/core/net.md).
### ``Efl.Io.Buffered_Stream`` ###
-Read the whole documentation in the ``Efl.Io.Buffered_Stream`` [API Reference
guide](/develop/api/efl/io/buffered_stream). It implements the
``Efl.Io.Reader``, ``Efl.Io.Writer`` and ``Efl.Io.Closer`` interfaces.
+Read the entire documentation in the ``Efl.Io.Buffered_Stream`` [API Reference
guide](/develop/api/efl/io/buffered_stream). It implements the
``Efl.Io.Reader``, ``Efl.Io.Writer`` and ``Efl.Io.Closer`` interfaces.
-This is a convenience object that adds buffered input and output to an
existing object (called the *inner* object) implementing the ``Efl.Io.Reader``
and/or ``Efl.Io.Writer`` interfaces.
+This is a convenient object which adds buffered input and output to an
existing object (called the *inner* object) implementing the ``Efl.Io.Reader``
and/or ``Efl.Io.Writer`` interfaces.
-The purpose of ``Efl.Io.Buffered_Stream`` is to overcome the following
limitations of these interfaces: The basic writer interface might write less
data than actually provided and the user is then responsible for retrying later
on when the interface is ready. Likewise, the basic reader interface might
provide less data than requested, and the user must wait and retry until all
data is read.
+The purpose of ``Efl.Io.Buffered_Stream`` is to overcome the following
limitations of these interfaces: The basic writer interface might write less
data than actually provided and the user is then responsible for retrying later
on when the interface is ready. Similarly the basic reader interface might
provide less data than requested and the user must wait and retry until all
data is read.
-``Efl.Io.Buffered_Stream`` uses internal Queues and Copier objects so that you
can simply "write and forget": You just need to write all your data in one
operation, and the Buffered_Stream object will take care of retrying and
guarantee that all your data is sent. Likewise, you can simply "read when
ready": Incoming data will be automatically accumulated and you can perform
your read when enough of it has been received.
+``Efl.Io.Buffered_Stream`` uses internal Queues and Copier objects so that you
can simply "write and forget". You only need to write all your data in one
operation and the Buffered_Stream object will take care of retrying and
guarantee that all your data is sent. You can also simply "read when ready":
Incoming data will be automatically accumulated and you can perform your read
when enough has been received.
-To achieve this, the writer interface of the Buffered_Stream object is
connected to an *output* ``Efl.Io.Queue`` and an ``Efl.Io.Copier`` connects
this queue to the writer interface of the inner object. Simultaneously, another
``Efl.Io.Copier`` connects the reader interface of the inner object to an
*input* ``Efl.Io.Queue`` which is accessible through the Buffered_Stream reader
interface.
+To achieve this the writer interface of the Buffered_Stream object is
connected to an *output* ``Efl.Io.Queue`` and an ``Efl.Io.Copier`` connects
this queue to the writer interface of the inner object. Simultaneously, another
``Efl.Io.Copier`` connects the reader interface of the inner object to an
*input* ``Efl.Io.Queue`` which is accessible through the Buffered_Stream reader
interface.
The most commonly used methods of ``Efl.Io.Buffered_Stream`` are:
--
