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

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. A selectable will express its interest in these events through the ::pn_selectable_capacity(), ::pn_selectable_pending(), and ::pn_selectable_deadline() calls.

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().

typedef pn_iterator_t pn_selectables_t

An iterator for selectables.

## Function Documentation

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

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

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

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_EXTERN void pn_selectable_expired | ( | pn_selectable_t * | selectable | ) |

Notify a selectable that its deadline has expired.

Parameters

  [in] | selectable | a selectable object

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

Free a selectable object.

Parameters

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

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_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_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_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_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_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_EXTERN void pn_selectable_on_error | ( | pn_selectable_t * | sel,
|  | void(*)(pn_selectable_t *) | error
| ) |  |

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

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

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

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

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

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_EXTERN void pn_selectable_release | ( | pn_selectable_t * | selectable | ) |

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

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_EXTERN void pn_selectable_set_reading | ( | pn_selectable_t * | sel,
|  | bool | reading
| ) |  |

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_EXTERN void pn_selectable_set_writing | ( | pn_selectable_t * | sel,
|  | bool | writing
| ) |  |

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

Terminate a selectable.

Parameters

  [in] | selectable | a selectable object

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_EXTERN pn_selectables_t* pn_selectables | ( | void |  | ) |

Construct a new selectables iterator.

Returns
  a pointer to a new selectables iterator

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

Free a selectables iterator.

Parameters

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

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