event_io_read

event_io_read — Initiate or continue a read operation for a fixed length

#include "event.h"

| int **event_io_read** ( | e, |   | |   | buf, |   | |   | buflen, |   | |   | state); |   |

Event * <var class="pdparam">e</var>; char * <var class="pdparam">buf</var>; int <var class="pdparam">buflen</var>; event_io_state * <var class="pdparam">state</var>;

Initiate or continue a read operation for a fixed length. If you need a record based reader, consider using the tryread APIs.

Initiates a read that will populate buf and buflen with the data requested. This function will not return success until it has completely obtained the length requested. It may return EVENT_IO_ERROR if an error is encountered before that time.

This function is intended to be used with comparatively small buffers. If you anticipate moving large chunks of data (where large means larger than the growbuf size) over a transport, you should consider using the growbuf code instead.

If the read cannot be satisfied immediately, this function stores state information into the state parameter and returns EVENT_IO_PENDING. state->needmask will be set to the mask required for scheduling purposes. The caller should call event_io_read when the scheduler indicates that the underlying event is signalled with state->needmask.

If the read failed, this function returns EVENT_IO_ERROR.

If the read completes, returns EVENT_IO_DONE.

When EVENT_IO_DONE is returned, the caller provided buf and buflen will be populated with the requested data. If multiple event_io_read calls were required to completely satisfy the request, the buf and buflen passed to the most recent call are used; this function does not cache the caller provided buffer address, on the assumption that it might be a stack variable, and as such, will unwind between event_io_read calls.

state must not be NULL, and must either be zero'ed out or be a value state structure previously used by other event_io_XXX routines.

It is advantageous to reuse state structures, as they try to avoid allocating memory if they already have an appropriately sized buffer.

When a state structure is no longer required, you should free resources by calling event_io_state_clean.

Returns EVENT_IO_EOF when no more data can be read from the file descriptor. This constant is available starting from Momentum 3.0.11.

Parameters

Return Values

For the return values see the description above.

Threading

Only call this function from the Scheduler thread.

Event Functions and tryread_until