Pipe wrapper
Ecore » Ecore main loop

These functions wrap the pipe / write / read functions to easily integrate its use into ecore's main loop. More...

## Typedefs

typedef struct _Ecore_Pipe | Ecore_Pipe
| A handle for pipes.
typedef void(* | Ecore_Pipe_Cb) (void *data, void *buffer, unsigned int nbyte)
| The callback that data written to the pipe is sent to.

## Functions

Ecore_Pipe * | ecore_pipe_add (Ecore_Pipe_Cb handler, const void *data)
| Creates two file descriptors (sockets on Windows).
Ecore_Pipe * | ecore_pipe_full_add (Ecore_Pipe_Cb handler, const void *data, int fd_read, int fd_write, Eina_Bool read_survive_fork, Eina_Bool write_survive_fork)
| Creates a pipe with more parameters.
void * | ecore_pipe_del (Ecore_Pipe *p)
| Frees an Ecore_Pipe object created with ecore_pipe_add().
Eina_Bool | ecore_pipe_write (Ecore_Pipe *p, const void *buffer, unsigned int nbytes)
| Writes on the file descriptor the data passed as parameter.
void | ecore_pipe_write_close (Ecore_Pipe *p)
| Closes the write end of an Ecore_Pipe object created with ecore_pipe_add().
void | ecore_pipe_read_close (Ecore_Pipe *p)
| Closes the read end of an Ecore_Pipe object created with ecore_pipe_add().
int | ecore_pipe_read_fd (Ecore_Pipe *p)
| Gets the pipe read file descriptor.
int | ecore_pipe_write_fd (Ecore_Pipe *p)
| Gets the pipe write file descriptor.
void | ecore_pipe_thaw (Ecore_Pipe *p)
| Starts monitoring again the pipe for reading.
void | ecore_pipe_freeze (Ecore_Pipe *p)
| Stops monitoring if necessary the pipe for reading.
int | ecore_pipe_wait (Ecore_Pipe *p, int message_count, double wait)
| Waits from another thread on the read side of a pipe.

## Detailed Description

These functions wrap the pipe / write / read functions to easily integrate its use into ecore's main loop.

The ecore_pipe_add() function creates file descriptors (sockets on Windows) and attach a handle to the ecore main loop. That handle is called when data is read in the pipe. To write data in the pipe, just call ecore_pipe_write(). When you are done, just call ecore_pipe_del().

For examples see here:

- tutorial_ecore_pipe_gstreamer_example
- tutorial_ecore_pipe_simple_example

## Function Documentation

## ecore_pipe_add()

Ecore_Pipe * ecore_pipe_add | ( | Ecore_Pipe_Cb | handler,
|  | const void * | data )

Creates two file descriptors (sockets on Windows).

Adds a callback that will be called when the file descriptor that is listened receives data. An event is also put in the event queue when data is received.

Parameters

  handler | The handler called when data is received.
  data | Data to pass to `handler` when it is called.

Returns
  A newly created Ecore_Pipe object if successful, `NULL` otherwise.

Examples
  ecore_pipe_gstreamer_example.c, and ecore_pipe_simple_example.c.

Referenced by ecore_fork_reset().

## ecore_pipe_full_add()

Ecore_Pipe * ecore_pipe_full_add | ( | Ecore_Pipe_Cb | handler,
|  | const void * | data,
|  | int | fd_read,
|  | int | fd_write,
|  | Eina_Bool | read_survive_fork,
|  | Eina_Bool | write_survive_fork )

Creates a pipe with more parameters.

Parameters

  handler | Same as ecore_pipe_add()
  data | Same as ecore_pipe_add()
  fd_read | An fd to use for reading or `-1` otherwise
  fd_write | An fd to use for writing or `-1` otherwise
  read_survive_fork | Should read fd survive a fork
  write_survive_fork | Should write fd survive a fork

This is the same as ecore_pipe_add() but with some added parameters.

Returns
  A pointer to the new Ecore_Pipe object on success, else NULL.

See also
  ecore_pipe_add()

References ECORE_FD_READ, ecore_main_fd_handler_add(), eina_file_close_on_exec(), EINA_MAIN_LOOP_CHECK_RETURN_VAL, EINA_TRUE, ERR, and fcntl().

## ecore_pipe_del()

void * ecore_pipe_del | ( | Ecore_Pipe * | p | ) |

Frees an Ecore_Pipe object created with ecore_pipe_add().

Parameters

  p | The Ecore_Pipe object to be freed.

Returns
  The pointer to the private data

Examples
  ecore_pipe_gstreamer_example.c, and ecore_pipe_simple_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

Referenced by ecore_fork_reset().

## ecore_pipe_write()

Eina_Bool ecore_pipe_write | ( | Ecore_Pipe * | p,
|  | const void * | buffer,
|  | unsigned int | nbytes )

Writes on the file descriptor the data passed as parameter.

Parameters

  p | The Ecore_Pipe object.
  buffer | The data to write into the pipe.
  nbytes | The size of the `buffer` in bytes.

Returns
  `EINA_TRUE` on a successful write, `EINA_FALSE` on error.

Examples
  ecore_pipe_gstreamer_example.c, and ecore_pipe_simple_example.c.

References EINA_FALSE, EINA_TRUE, and ERR.

Referenced by ecore_fork_reset(), and evas_async_events_put().

## ecore_pipe_write_close()

void ecore_pipe_write_close | ( | Ecore_Pipe * | p | ) |

Closes the write end of an Ecore_Pipe object created with ecore_pipe_add().

Parameters

  p | The Ecore_Pipe object.

Examples
  ecore_pipe_simple_example.c.

## ecore_pipe_read_close()

void ecore_pipe_read_close | ( | Ecore_Pipe * | p | ) |

Closes the read end of an Ecore_Pipe object created with ecore_pipe_add().

Parameters

  p | The Ecore_Pipe object.

Examples
  ecore_pipe_simple_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN.

## ecore_pipe_read_fd()

int ecore_pipe_read_fd | ( | Ecore_Pipe * | p | ) |

Gets the pipe read file descriptor.

Parameters

  p | The Ecore_Pipe object query.

Returns
  The file descriptor, or `-1` if none

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ecore_pipe_write_fd()

int ecore_pipe_write_fd | ( | Ecore_Pipe * | p | ) |

Gets the pipe write file descriptor.

Parameters

  p | The Ecore_Pipe object query.

Returns
  The file descriptor, or `-1` if none

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ecore_pipe_thaw()

void ecore_pipe_thaw | ( | Ecore_Pipe * | p | ) |

Starts monitoring again the pipe for reading.

See ecore_pipe_freeze() for stopping the monitoring activity. This will not work if ecore_pipe_read_close() was previously called on the same pipe.

Parameters

  p | The Ecore_Pipe object.

Since
  1.1

References ECORE_FD_READ, ecore_main_fd_handler_add(), and EINA_MAIN_LOOP_CHECK_RETURN.

## ecore_pipe_freeze()

void ecore_pipe_freeze | ( | Ecore_Pipe * | p | ) |

Stops monitoring if necessary the pipe for reading.

See ecore_pipe_thaw() for monitoring it again.

Parameters

  p | The Ecore_Pipe object.

Since
  1.1

References EINA_MAIN_LOOP_CHECK_RETURN.

## ecore_pipe_wait()

int ecore_pipe_wait | ( | Ecore_Pipe * | p,
|  | int | message_count,
|  | double | wait )

Waits from another thread on the read side of a pipe.

Parameters

  p | The pipe to watch on.
  message_count | The minimum number of messages to wait for before exiting.
  wait | The amount of time in seconds to wait before exiting.

Returns
  The number of message caught during the wait call.

Since
  1.1

Negative value for `wait` means infite wait.

Referenced by ecore_main_loop_thread_safe_call_wait(), and evas_async_events_process().