unbound: util/tube.h File Reference

unbound 0.1

Data Structures | Typedefs | Functions
tube.h File Reference

This file contains pipe service functions. More...

## Data Structures
struct | tube
| A pipe. More...
struct | tube_res_list
| List of results (arbitrary command serializations) to write back. More...

## Typedefs
typedef void | tube_callback_type(struct tube *, uint8_t *, size_t, int, void *)
| Callback from pipe listen function void mycallback(tube, msg, len, error, user_argument); if error is true (NETEVENT_*), msg is probably NULL.

## Functions
struct tube * | tube_create (void)
| Create a pipe.
void | tube_delete (struct tube *tube)
| Delete and destroy a pipe.
int | tube_write_msg (struct tube *tube, uint8_t *buf, uint32_t len, int nonblock)
| Write length bytes followed by message.
int | tube_read_msg (struct tube *tube, uint8_t **buf, uint32_t *len, int nonblock)
| Read length bytes followed by message.
void | tube_close_read (struct tube *tube)
| Close read part of the pipe.
void | tube_close_write (struct tube *tube)
| Close write part of the pipe.
int | tube_poll (struct tube *tube)
| See if data is ready for reading on the tube without blocking.
int | tube_wait (struct tube *tube)
| Wait for data to be ready for reading on the tube.
int | tube_wait_timeout (struct tube *tube, int msec)
| Wait for data to be ready with a timeout.
int | tube_read_fd (struct tube *tube)
| Get FD that is readable when new information arrives.
int | tube_setup_bg_listen (struct tube *tube, struct comm_base *base, tube_callback_type *cb, void *arg)
| Start listening for information over the pipe.
void | tube_remove_bg_listen (struct tube *tube)
| Remove bg listen setup from event base.
int | tube_setup_bg_write (struct tube *tube, struct comm_base *base)
| Start background write handler for the pipe.
void | tube_remove_bg_write (struct tube *tube)
| Remove bg write setup from event base.
int | tube_queue_item (struct tube *tube, uint8_t *msg, size_t len)
| Append data item to background list of writes.
int | tube_handle_listen (struct comm_point *c, void *arg, int error, struct comm_reply *reply_info)
| for fptr wlist, callback function
int | tube_handle_write (struct comm_point *c, void *arg, int error, struct comm_reply *reply_info)
| for fptr wlist, callback function
void | tube_handle_signal (int fd, short events, void *arg)
| for fptr wlist, winsock signal event callback function

## Detailed Description

This file contains pipe service functions.

## Function Documentation

## ◆ tube_create()

struct tube * tube_create | ( | void |  | ) |

Create a pipe.

Returns
  : new tube struct or NULL on error.

References fd_set_nonblock(), log_err(), socketpair, tube::sr, tube::sw, and tube_delete().

Referenced by ub_ctx_create(), and worker_create().

## ◆ tube_delete()

void tube_delete | ( | struct tube * | tube | ) |

Delete and destroy a pipe.

Parameters

  tube | to delete

References tube_close_read(), tube_close_write(), tube_remove_bg_listen(), and tube_remove_bg_write().

Referenced by tube_create(), ub_ctx_create(), ub_ctx_delete(), worker_create(), and worker_delete().

## ◆ tube_write_msg()

int tube_write_msg | ( | struct tube * | tube,
|  | uint8_t * | buf,
|  | uint32_t | len,
|  | int | nonblock
| ) |  |

Write length bytes followed by message.

Parameters

  tube | the tube to write on. If that tube is a pipe, its write fd is used as the socket to write on. Is nonblocking. Set to blocking by the function, and back to non-blocking at exit of function.
  buf | the message.
  len | length of message.
  nonblock | if set to true, the first write is nonblocking. If the first write fails the function returns -1. If set false, the first write is blocking.

Returns
  : all remainder writes are nonblocking. return 0 on error, in that case blocking/nonblocking of socket is unknown. return 1 if all OK.

References tube_res_list::buf, fd_set_block(), fd_set_nonblock(), tube_res_list::len, log_err(), and tube::sw.

Referenced by distribute_cmd(), libworker_dobg(), server_stats_reply(), ub_cancel(), ub_resolve_async(), ub_stop_bg(), and worker_send_cmd().

## ◆ tube_read_msg()

int tube_read_msg | ( | struct tube * | tube,
|  | uint8_t ** | buf,
|  | uint32_t * | len,
|  | int | nonblock
| ) |  |

Read length bytes followed by message.

Parameters

  tube | The tube to read on. If that tube is a pipe, its read fd is used as the socket to read on. Is nonblocking. Set to blocking by the function, and back to non-blocking at exit of function.
  buf | the message, malloced.
  len | length of message, returned.
  nonblock | if set to true, the first read is nonblocking. If the first read fails the function returns -1. If set false, the first read is blocking.

Returns
  : all remainder reads are nonblocking. return 0 on error, in that case blocking/nonblocking of socket is unknown. On EOF 0 is returned. return 1 if all OK.

References tube_res_list::buf, fd_set_block(), fd_set_nonblock(), tube_res_list::len, log_err(), and tube::sr.

Referenced by daemon_remote_exec(), server_stats_obtain(), ub_process(), ub_stop_bg(), and ub_wait().

## ◆ tube_close_read()

void tube_close_read | ( | struct tube * | tube | ) |

Close read part of the pipe.

The tube can no longer be read from.

Parameters

  tube | tube to operate on.

References tube::sr.

Referenced by daemon_start_others(), libworker_bg(), libworker_dobg(), and tube_delete().

## ◆ tube_close_write()

void tube_close_write | ( | struct tube * | tube | ) |

Close write part of the pipe.

The tube can no longer be written to.

Parameters

  tube | tube to operate on.

References tube::sw.

Referenced by libworker_bg(), libworker_dobg(), thread_start(), and tube_delete().

## ◆ tube_poll()

int tube_poll | ( | struct tube * | tube | ) |

See if data is ready for reading on the tube without blocking.

Parameters

  tube | tube to check for readable items

Returns
  true if readable items are present. False if not (or error). true on pipe_closed.

References pollit(), and tube::sr.

Referenced by ub_poll().

## ◆ tube_wait()

int tube_wait | ( | struct tube * | tube | ) |

Wait for data to be ready for reading on the tube.

is blocking. No timeout.

Parameters

  tube | the tube to wait on.

Returns
  : if there was something to read (false on error). true on pipe_closed.

References pollit(), and tube::sr.

Referenced by ub_wait().

## ◆ tube_wait_timeout()

int tube_wait_timeout | ( | struct tube * | tube,
|  | int | msec
| ) |  |

Wait for data to be ready with a timeout.

Parameters

  tube | the tube to wait on.
  msec | timeout in milliseconds.

Returns
  1 if there is something to read within timeout, readability. 0 on a timeout. On failures -1, like errors.

References tube::sr.

Referenced by server_stats_obtain().

## ◆ tube_read_fd()

int tube_read_fd | ( | struct tube * | tube | ) |

Get FD that is readable when new information arrives.

Parameters

  tube |

Returns
  file descriptor.

References tube::sr.

Referenced by ub_fd().

## ◆ tube_setup_bg_listen()

int tube_setup_bg_listen | ( | struct tube * | tube,
|  | struct comm_base * | base,
|  | tube_callback_type * | cb,
|  | void * | arg
| ) |  |

Start listening for information over the pipe.

Background registration of a read listener, callback when read completed. Do not mix with tube_read_msg style direct reads from the pipe.

Parameters

  tube | tube to listen on
  base | what base to register event callback.
  cb | callback routine.
  arg | user argument for callback routine.

Returns
  true if successful, false on error.

References tube::listen_arg, tube::listen_cb, tube::listen_com, log_err(), and tube::sr.

Referenced by libworker_dobg(), and worker_init().

## ◆ tube_remove_bg_listen()

void tube_remove_bg_listen | ( | struct tube * | tube | ) |

Remove bg listen setup from event base.

Parameters

  tube | what tube to cleanup

References tube::cmd_msg, comm_point_delete(), and tube::listen_com.

Referenced by libworker_dobg(), and tube_delete().

## ◆ tube_setup_bg_write()

int tube_setup_bg_write | ( | struct tube * | tube,
|  | struct comm_base * | base
| ) |  |

Start background write handler for the pipe.

Do not mix with tube_write_msg style direct writes to the pipe.

Parameters

  tube | tube to write on
  base | what base to register event handler on.

Returns
  true if successful, false on error.

References log_err(), tube::res_com, and tube::sw.

Referenced by libworker_dobg().

## ◆ tube_remove_bg_write()

void tube_remove_bg_write | ( | struct tube * | tube | ) |

Remove bg write setup from event base.

Parameters

  tube | what tube to cleanup

References tube_res_list::buf, comm_point_delete(), tube_res_list::next, tube::res_com, tube::res_last, and tube::res_list.

Referenced by libworker_dobg(), and tube_delete().

## ◆ tube_queue_item()

int tube_queue_item | ( | struct tube * | tube,
|  | uint8_t * | msg,
|  | size_t | len
| ) |  |

Append data item to background list of writes.

Mallocs a list entry behind the scenes. Not locked behind the scenes, call from one thread or lock on outside.

Parameters

  tube | what tube to queue on.
  msg | memory message to send. Is free()d after use. Put at the end of the to-send queue.
  len | length of item.

Returns
  0 on failure (msg freed).

References tube_res_list::buf, tube_res_list::len, log_err(), tube_res_list::next, tube::res_com, tube::res_last, and tube::res_list.

Referenced by add_bg_result().