| // Copyright 2018 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| #ifndef LIB_ASYNC_EXCEPTION_H_ |
| #define LIB_ASYNC_EXCEPTION_H_ |
| |
| #include <lib/async/dispatcher.h> |
| |
| __BEGIN_CDECLS |
| |
| // Handles receipt of packets containing exception reports. |
| // |
| // The |status| is |ZX_OK| if the packet was successfully delivered and |data| |
| // contains the information from the packet, otherwise |data| is null. |
| // The |status| is |ZX_ERR_CANCELED| if the dispatcher was shut down. |
| typedef void(async_exception_handler_t)(async_dispatcher_t* dispatcher, |
| async_exception_t* exception, |
| zx_status_t status, |
| const zx_port_packet_t* report); |
| |
| // Holds content for an exception packet receiver and its handler. |
| // |
| // The client is responsible for retaining the structure in memory |
| // (and unmodified) until all packets have been received by the handler or the |
| // dispatcher shuts down. |
| // |
| // Multiple packets may be delivered to the same receiver concurrently. |
| struct async_exception { |
| // Private state owned by the dispatcher, initialize to zero with |ASYNC_STATE_INIT|. |
| async_state_t state; |
| |
| // The handler to invoke when a packet is received. |
| async_exception_handler_t* handler; |
| |
| // The task we're watching. |
| zx_handle_t task; |
| |
| // The options to pass to zx_task_bind_exception_port(). |
| uint32_t options; |
| }; |
| |
| // Bind the async port to the task's exception port. |
| // |
| // Returns |ZX_OK| if task's exception port was successfully bound to. |
| // Returns |ZX_ERR_BAD_STATE| if the dispatcher is shutting down. |
| // Returns |ZX_ERR_NOT_SUPPORTED| if not supported by the dispatcher. |
| // Other error values are possible. See the documentation for |
| // |zx_task_bind_exception_port()|. |
| // |
| // This operation is thread-safe. |
| zx_status_t async_bind_exception_port(async_dispatcher_t* dispatcher, |
| async_exception_t* exception); |
| |
| // Unbind the async port from |task|'s exception port. |
| // |
| // Returns |ZX_OK| if the task's exception port was successfully unbound. |
| // Returns |ZX_ERR_NOT_FOUND| if the port is not bound. |
| // Returns |ZX_ERR_NOT_SUPPORTED| if not supported by the dispatcher. |
| // Other error values are possible. See the documentation for |
| // |zx_task_bind_exception_port()|. |
| // |
| // This operation is thread-safe. |
| zx_status_t async_unbind_exception_port(async_dispatcher_t* dispatcher, |
| async_exception_t* exception); |
| |
| // Resume |task| after having processed an exception for it. |
| // |options| is passed to |zx_task_resume_from_exception()|. |
| // |
| // Returns |ZX_OK| if the task was resumed. |
| // Returns |ZX_ERR_BAD_STATE| if the dispatcher is shutting down. |
| // Returns |ZX_ERR_NOT_SUPPORTED| if not supported by the dispatcher. |
| // Other error values are possible. See the documentation for |
| // |zx_task_resume_from_exception()|. |
| // |
| // This operation is thread-safe. |
| zx_status_t async_resume_from_exception(async_dispatcher_t* dispatcher, |
| async_exception_t* exception, |
| zx_handle_t task, |
| uint32_t options); |
| |
| __END_CDECLS |
| |
| #endif // LIB_ASYNC_EXCEPTION_H_ |