Selectable

## Typedefs

typedef pn_iterator_t | pn_selectables_t
| An iterator for selectables. More...
typedef struct pn_selectable_t | pn_selectable_t
| A selectable object provides an interface that can be used to incorporate proton's I/O into third party event loops. More...

## Functions

PN_EXTERN pn_selectables_t * | pn_selectables (void)
| Construct a new selectables iterator. More...
PN_EXTERN pn_selectable_t * | pn_selectables_next (pn_selectables_t *selectables)
| Get the next selectable from an iterator. More...
PN_EXTERN void | pn_selectables_free (pn_selectables_t *selectables)
| Free a selectables iterator. More...
PN_EXTERN pn_selectable_t * | pn_selectable (void)
PN_EXTERN void | pn_selectable_on_readable (pn_selectable_t *sel, void(*readable)(pn_selectable_t *))
PN_EXTERN void | pn_selectable_on_writable (pn_selectable_t *sel, void(*writable)(pn_selectable_t *))
PN_EXTERN void | pn_selectable_on_expired (pn_selectable_t *sel, void(*expired)(pn_selectable_t *))
PN_EXTERN void | pn_selectable_on_error (pn_selectable_t *sel, void(*error)(pn_selectable_t *))
PN_EXTERN void | pn_selectable_on_release (pn_selectable_t *sel, void(*release)(pn_selectable_t *))
PN_EXTERN void | pn_selectable_on_finalize (pn_selectable_t *sel, void(*finalize)(pn_selectable_t *))
PN_EXTERN pn_record_t * | pn_selectable_attachments (pn_selectable_t *sel)
PN_EXTERN pn_socket_t | pn_selectable_get_fd (pn_selectable_t *selectable)
| Get the file descriptor associated with a selectable. More...
PN_EXTERN void | pn_selectable_set_fd (pn_selectable_t *selectable, pn_socket_t fd)
| Set the file descriptor associated with a selectable. More...
PN_EXTERN bool | pn_selectable_is_reading (pn_selectable_t *selectable)
| Check if a selectable is interested in readable events. More...
PN_EXTERN void | pn_selectable_set_reading (pn_selectable_t *sel, bool reading)
PN_EXTERN bool | pn_selectable_is_writing (pn_selectable_t *selectable)
| Check if a selectable is interested in writable events. More...
PN_EXTERN void | pn_selectable_set_writing (pn_selectable_t *sel, bool writing)
PN_EXTERN pn_timestamp_t | pn_selectable_get_deadline (pn_selectable_t *selectable)
| Get the next deadline for a selectable. More...
PN_EXTERN void | pn_selectable_set_deadline (pn_selectable_t *sel, pn_timestamp_t deadline)
PN_EXTERN void | pn_selectable_readable (pn_selectable_t *selectable)
| Notify a selectable that the file descriptor is readable. More...
PN_EXTERN void | pn_selectable_writable (pn_selectable_t *selectable)
| Notify a selectable that the file descriptor is writable. More...
PN_EXTERN void | pn_selectable_error (pn_selectable_t *selectable)
| Notify a selectable that there is an error on the file descriptor. More...
PN_EXTERN void | pn_selectable_expired (pn_selectable_t *selectable)
| Notify a selectable that its deadline has expired. More...
PN_EXTERN bool | pn_selectable_is_registered (pn_selectable_t *selectable)
| Check if a selectable is registered. More...
PN_EXTERN void | pn_selectable_set_registered (pn_selectable_t *selectable, bool registered)
| Set the registered flag for a selectable. More...
PN_EXTERN bool | pn_selectable_is_terminal (pn_selectable_t *selectable)
| Check if a selectable is in the terminal state. More...
PN_EXTERN void | pn_selectable_terminate (pn_selectable_t *selectable)
| Terminate a selectable. More...
PN_EXTERN void | pn_selectable_release (pn_selectable_t *selectable)
PN_EXTERN void | pn_selectable_free (pn_selectable_t *selectable)
| Free a selectable object. More...
PN_EXTERN void | pn_selectable_collect (pn_selectable_t *selectable, pn_collector_t *collector)
| Configure a selectable with a set of callbacks that emit readable, writable, and expired events into the supplied collector. More...

## Detailed Description

## Typedef Documentation

## pn_selectable_t

typedef struct pn_selectable_t pn_selectable_t

A selectable object provides an interface that can be used to incorporate proton's I/O into third party event loops.

Every selectable is associated with exactly one file descriptor. Selectables may be interested in three kinds of events, read events, write events, and timer events.

When a read, write, or timer event occurs, the selectable must be notified by calling pn_selectable_readable(), pn_selectable_writable(), and pn_selectable_expired() as appropriate.

Once a selectable reaches a terminal state (see pn_selectable_is_terminal()), it will never be interested in events of any kind. When this occurs it should be removed from the external event loop and discarded using pn_selectable_free().

## pn_selectables_t

typedef pn_iterator_t pn_selectables_t

An iterator for selectables.

## Function Documentation

## pn_selectable()

PN_EXTERN pn_selectable_t* pn_selectable | ( | void |  | ) |

## pn_selectable_attachments()

PN_EXTERN pn_record_t* pn_selectable_attachments | ( | pn_selectable_t * | sel | ) |

## pn_selectable_collect()

PN_EXTERN void pn_selectable_collect | ( | pn_selectable_t * | selectable,
|  | pn_collector_t * | collector
| ) |  |

Configure a selectable with a set of callbacks that emit readable, writable, and expired events into the supplied collector.

Parameters

  [in] | selectable | a selectable objet
  [in] | collector | a collector object

## pn_selectable_error()

PN_EXTERN void pn_selectable_error | ( | pn_selectable_t * | selectable | ) |

Notify a selectable that there is an error on the file descriptor.

Parameters

  [in] | selectable | a selectable object

## pn_selectable_expired()

PN_EXTERN void pn_selectable_expired | ( | pn_selectable_t * | selectable | ) |

Notify a selectable that its deadline has expired.

Parameters

  [in] | selectable | a selectable object

## pn_selectable_free()

PN_EXTERN void pn_selectable_free | ( | pn_selectable_t * | selectable | ) |

Free a selectable object.

Parameters

  [in] | selectable | a selectable object (or NULL)

## pn_selectable_get_deadline()

PN_EXTERN pn_timestamp_t pn_selectable_get_deadline | ( | pn_selectable_t * | selectable | ) |

Get the next deadline for a selectable.

A selectable with a deadline is interested in being notified when that deadline expires. Zero indicates there is currently no deadline.

Parameters

  [in] | selectable | a selectable object

Returns
  the next deadline or zero

## pn_selectable_get_fd()

PN_EXTERN pn_socket_t pn_selectable_get_fd | ( | pn_selectable_t * | selectable | ) |

Get the file descriptor associated with a selectable.

Parameters

  [in] | selectable | a selectable object

Returns
  the file descriptor associated with the selectable

## pn_selectable_is_reading()

PN_EXTERN bool pn_selectable_is_reading | ( | pn_selectable_t * | selectable | ) |

Check if a selectable is interested in readable events.

Parameters

  [in] | selectable | a selectable object

Returns
  true iff the selectable is interested in read events

## pn_selectable_is_registered()

PN_EXTERN bool pn_selectable_is_registered | ( | pn_selectable_t * | selectable | ) |

Check if a selectable is registered.

This flag is set via pn_selectable_set_registered() and can be used for tracking whether a given selectable has been registerd with an external event loop.

Parameters

  [in] | selectable |

Returns
  true if the selectable is registered

## pn_selectable_is_terminal()

PN_EXTERN bool pn_selectable_is_terminal | ( | pn_selectable_t * | selectable | ) |

Check if a selectable is in the terminal state.

A selectable that is in the terminal state will never be interested in being notified of events of any kind ever again. Once a selectable reaches this state it should be removed from any external I/O loops and freed in order to reclaim any resources associated with it.

Parameters

  [in] | selectable | a selectable object

Returns
  true if the selectable is in the terminal state, false otherwise

## pn_selectable_is_writing()

PN_EXTERN bool pn_selectable_is_writing | ( | pn_selectable_t * | selectable | ) |

Check if a selectable is interested in writable events.

Parameters

  [in] | selectable | a selectable object

Returns
  true iff the selectable is interested in writable events

## pn_selectable_on_error()

PN_EXTERN void pn_selectable_on_error | ( | pn_selectable_t * | sel,
|  | void(*)(pn_selectable_t *) | error
| ) |  |

## pn_selectable_on_expired()

PN_EXTERN void pn_selectable_on_expired | ( | pn_selectable_t * | sel,
|  | void(*)(pn_selectable_t *) | expired
| ) |  |

## pn_selectable_on_finalize()

PN_EXTERN void pn_selectable_on_finalize | ( | pn_selectable_t * | sel,
|  | void(*)(pn_selectable_t *) | finalize
| ) |  |

## pn_selectable_on_readable()

PN_EXTERN void pn_selectable_on_readable | ( | pn_selectable_t * | sel,
|  | void(*)(pn_selectable_t *) | readable
| ) |  |

## pn_selectable_on_release()

PN_EXTERN void pn_selectable_on_release | ( | pn_selectable_t * | sel,
|  | void(*)(pn_selectable_t *) | release
| ) |  |

## pn_selectable_on_writable()

PN_EXTERN void pn_selectable_on_writable | ( | pn_selectable_t * | sel,
|  | void(*)(pn_selectable_t *) | writable
| ) |  |

## pn_selectable_readable()

PN_EXTERN void pn_selectable_readable | ( | pn_selectable_t * | selectable | ) |

Notify a selectable that the file descriptor is readable.

Parameters

  [in] | selectable | a selectable object

## pn_selectable_release()

PN_EXTERN void pn_selectable_release | ( | pn_selectable_t * | selectable | ) |

## pn_selectable_set_deadline()

PN_EXTERN void pn_selectable_set_deadline | ( | pn_selectable_t * | sel,
|  | pn_timestamp_t | deadline
| ) |  |

## pn_selectable_set_fd()

PN_EXTERN void pn_selectable_set_fd | ( | pn_selectable_t * | selectable,
|  | pn_socket_t | fd
| ) |  |

Set the file descriptor associated with a selectable.

Parameters

  [in] | selectable | a selectable object
  [in] | fd | the file descriptor

## pn_selectable_set_reading()

PN_EXTERN void pn_selectable_set_reading | ( | pn_selectable_t * | sel,
|  | bool | reading
| ) |  |

## pn_selectable_set_registered()

PN_EXTERN void pn_selectable_set_registered | ( | pn_selectable_t * | selectable,
|  | bool | registered
| ) |  |

Set the registered flag for a selectable.

See pn_selectable_is_registered() for details.

Parameters

  [in] | selectable | a selectable object
  [in] | registered | the registered flag

## pn_selectable_set_writing()

PN_EXTERN void pn_selectable_set_writing | ( | pn_selectable_t * | sel,
|  | bool | writing
| ) |  |

## pn_selectable_terminate()

PN_EXTERN void pn_selectable_terminate | ( | pn_selectable_t * | selectable | ) |

Terminate a selectable.

Parameters

  [in] | selectable | a selectable object

## pn_selectable_writable()

PN_EXTERN void pn_selectable_writable | ( | pn_selectable_t * | selectable | ) |

Notify a selectable that the file descriptor is writable.

Parameters

  [in] | selectable | a selectable object

## pn_selectables()

PN_EXTERN pn_selectables_t* pn_selectables | ( | void |  | ) |

Construct a new selectables iterator.

Returns
  a pointer to a new selectables iterator

## pn_selectables_free()

PN_EXTERN void pn_selectables_free | ( | pn_selectables_t * | selectables | ) |

Free a selectables iterator.

Parameters

  [in] | selectables | a selectables iterator (or NULL)

## pn_selectables_next()

PN_EXTERN pn_selectable_t* pn_selectables_next | ( | pn_selectables_t * | selectables | ) |

Get the next selectable from an iterator.

Parameters

  [in] | selectables | a selectable iterator

Returns
  the next selectable from the iterator