| #ifndef PROTON_SELECTABLE_H |
| #define PROTON_SELECTABLE_H 1 |
| |
| /* |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| */ |
| |
| #include <proton/import_export.h> |
| #include <proton/object.h> |
| #include <proton/event.h> |
| #include <proton/type_compat.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** |
| * @cond INTERNAL |
| */ |
| |
| /** |
| * A ::pn_socket_t provides an abstract handle to an IO stream. The |
| * pipe version is uni-directional. The network socket version is |
| * bi-directional. Both are non-blocking. |
| * |
| * pn_socket_t handles from pn_pipe() may only be used with |
| * pn_read(), pn_write(), pn_close() and pn_selector_select(). |
| * |
| * pn_socket_t handles from pn_listen(), pn_accept() and |
| * pn_connect() must perform further IO using Proton functions. |
| * Mixing Proton io.h functions with native IO functions on the same |
| * handles will result in undefined behavior. |
| * |
| * pn_socket_t handles may only be used with a single pn_io_t during |
| * their lifetime. |
| */ |
| #if defined(_WIN32) && ! defined(__CYGWIN__) |
| #ifdef _WIN64 |
| typedef unsigned __int64 pn_socket_t; |
| #else |
| typedef unsigned int pn_socket_t; |
| #endif |
| #define PN_INVALID_SOCKET (pn_socket_t)(~0) |
| #else |
| typedef int pn_socket_t; |
| #define PN_INVALID_SOCKET (-1) |
| #endif |
| |
| /** |
| * 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(). |
| */ |
| typedef struct pn_selectable_t pn_selectable_t; |
| |
| PNX_EXTERN pn_selectable_t *pn_selectable(void); |
| |
| PNX_EXTERN void pn_selectable_on_readable(pn_selectable_t *sel, void (*readable)(pn_selectable_t *)); |
| PNX_EXTERN void pn_selectable_on_writable(pn_selectable_t *sel, void (*writable)(pn_selectable_t *)); |
| PNX_EXTERN void pn_selectable_on_expired(pn_selectable_t *sel, void (*expired)(pn_selectable_t *)); |
| PNX_EXTERN void pn_selectable_on_error(pn_selectable_t *sel, void (*error)(pn_selectable_t *)); |
| PNX_EXTERN void pn_selectable_on_release(pn_selectable_t *sel, void (*release)(pn_selectable_t *)); |
| PNX_EXTERN void pn_selectable_on_finalize(pn_selectable_t *sel, void (*finalize)(pn_selectable_t *)); |
| |
| PNX_EXTERN pn_record_t *pn_selectable_attachments(pn_selectable_t *sel); |
| |
| /** |
| * Get the file descriptor associated with a selectable. |
| * |
| * @param[in] selectable a selectable object |
| * @return the file descriptor associated with the selectable |
| */ |
| PNX_EXTERN pn_socket_t pn_selectable_get_fd(pn_selectable_t *selectable); |
| |
| /** |
| * Set the file descriptor associated with a selectable. |
| * |
| * @param[in] selectable a selectable object |
| * @param[in] fd the file descriptor |
| */ |
| PNX_EXTERN void pn_selectable_set_fd(pn_selectable_t *selectable, pn_socket_t fd); |
| |
| /** |
| * Check if a selectable is interested in readable events. |
| * |
| * @param[in] selectable a selectable object |
| * @return true iff the selectable is interested in read events |
| */ |
| PNX_EXTERN bool pn_selectable_is_reading(pn_selectable_t *selectable); |
| |
| PNX_EXTERN void pn_selectable_set_reading(pn_selectable_t *sel, bool reading); |
| |
| /** |
| * Check if a selectable is interested in writable events. |
| * |
| * @param[in] selectable a selectable object |
| * @return true iff the selectable is interested in writable events |
| */ |
| PNX_EXTERN bool pn_selectable_is_writing(pn_selectable_t *selectable); |
| |
| PNX_EXTERN void pn_selectable_set_writing(pn_selectable_t *sel, bool writing); |
| |
| /** |
| * 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. |
| * |
| * @param[in] selectable a selectable object |
| * @return the next deadline or zero |
| */ |
| PNX_EXTERN pn_timestamp_t pn_selectable_get_deadline(pn_selectable_t *selectable); |
| |
| PNX_EXTERN void pn_selectable_set_deadline(pn_selectable_t *sel, pn_timestamp_t deadline); |
| |
| /** |
| * Notify a selectable that the file descriptor is readable. |
| * |
| * @param[in] selectable a selectable object |
| */ |
| PNX_EXTERN void pn_selectable_readable(pn_selectable_t *selectable); |
| |
| /** |
| * Notify a selectable that the file descriptor is writable. |
| * |
| * @param[in] selectable a selectable object |
| */ |
| PNX_EXTERN void pn_selectable_writable(pn_selectable_t *selectable); |
| |
| /** |
| * Notify a selectable that there is an error on the file descriptor. |
| * |
| * @param[in] selectable a selectable object |
| */ |
| PNX_EXTERN void pn_selectable_error(pn_selectable_t *selectable); |
| |
| /** |
| * Notify a selectable that its deadline has expired. |
| * |
| * @param[in] selectable a selectable object |
| */ |
| PNX_EXTERN void pn_selectable_expired(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 registered |
| * with an external event loop. |
| * |
| * @param[in] selectable |
| * @return true if the selectable is registered |
| */ |
| PNX_EXTERN bool pn_selectable_is_registered(pn_selectable_t *selectable); |
| |
| /** |
| * Set the registered flag for a selectable. |
| * |
| * See ::pn_selectable_is_registered() for details. |
| * |
| * @param[in] selectable a selectable object |
| * @param[in] registered the registered flag |
| */ |
| PNX_EXTERN void pn_selectable_set_registered(pn_selectable_t *selectable, bool registered); |
| |
| /** |
| * 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. |
| * |
| * @param[in] selectable a selectable object |
| * @return true if the selectable is in the terminal state, false otherwise |
| */ |
| PNX_EXTERN bool pn_selectable_is_terminal(pn_selectable_t *selectable); |
| |
| /** |
| * Terminate a selectable. |
| * |
| * @param[in] selectable a selectable object |
| */ |
| PNX_EXTERN void pn_selectable_terminate(pn_selectable_t *selectable); |
| |
| PNX_EXTERN void pn_selectable_release(pn_selectable_t *selectable); |
| |
| /** |
| * Free a selectable object. |
| * |
| * @param[in] selectable a selectable object (or NULL) |
| */ |
| PNX_EXTERN void pn_selectable_free(pn_selectable_t *selectable); |
| |
| /** |
| * Configure a selectable with a set of callbacks that emit readable, |
| * writable, and expired events into the supplied collector. |
| * |
| * @param[in] selectable a selectable object |
| * @param[in] collector a collector object |
| */ |
| PNX_EXTERN void pn_selectable_collect(pn_selectable_t *selectable, pn_collector_t *collector); |
| |
| /** |
| * @endcond |
| */ |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* selectable.h */ |