| // Copyright 2019 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. |
| library fuchsia.diagnostics.stream; |
| using zx; |
| |
| /// A component with records for the Diagnostics system to retrieve. |
| /// |
| /// To record diagnostics, a component allocates a VMO and begins writing records into the buffer, |
| /// incrementing a header value after each write to inform readers how much of the buffer has been |
| /// filled. |
| /// |
| /// If any retrievers are connected, the `Source` sends them `OnBufferInit` events for each |
| /// diagnostic buffer created. |
| /// |
| /// When the buffer fills, the `Source` sends `OnBufferDone` to the retrievers, and will wait for |
| /// all notified retrievers to reply with `RetireBuffer` when they have finished reading from the |
| /// buffer. |
| /// |
| /// When all readers of the buffer have finished, the `Source` may recycle the buffer by zeroing it |
| /// and sending `OnBufferInit` again to connected retrievers. |
| /// |
| /// Once a `Source` has sent `OnBufferDone` to a retriever, it is up to the `Source` to handle new |
| /// records that are generated while the retriever drains the buffer. Double buffering is |
| /// recommended to prevent excessive blocking, but this protocol does not mandate a specific |
| /// approach to handling records generated while buffers are full. |
| @discoverable |
| protocol Source { |
| /// Notifies the connected retriever of a new stream buffer. Should be emitted as soon as each |
| /// buffer is (re)initialized. |
| /// |
| /// `latest` should be read-only. |
| -> OnBufferInit(resource struct { |
| latest zx.handle:VMO; |
| }); |
| |
| /// Asks the connected retriever to finish working with `buffer`, usually because the `Source` |
| /// does not intend to write further records. |
| -> OnBufferDone(struct { |
| buffer zx.koid; |
| }); |
| |
| /// Notifies the `Source` that the retriever is done reading from the buffer. If the `Source` |
| /// wishes it should zero the buffer's contents and recycle it for future records. Buffers must |
| /// be re-sent via `OnBufferInit` after they're zeroed. |
| RetireBuffer(struct { |
| buffer zx.koid; |
| }); |
| }; |