1.. _module-pw_channel: 2 3========== 4pw_channel 5========== 6.. pigweed-module:: 7 :name: pw_channel 8 9.. cpp:namespace:: pw::channel 10 11------------------ 12Channel attributes 13------------------ 14Channels may be reliable, readable, writable, or seekable. A channel may be 15substituted for another as long as it provides at least the same set of 16capabilities; additional capabilities are okay. The channel's data type 17(datagram or byte) implies different read/write semantics, so datagram/byte 18channels cannot be used interchangeably in general. 19 20Using datagram channels as byte channels 21======================================== 22For datagram channels, the exact bytes provided to a write call will appear in a 23read call on the other end. A zero-byte datagram write results in a zero-byte 24datagram read, so empty datagrams may convey information. 25 26For byte channels, bytes written may be grouped differently when read. A 27zero-length byte write is meaningless and will not result in a zero-length byte 28read. If a zero-length byte read occurs, it is ignored. 29 30To facilitate simple code reuse, datagram-oriented channels may used as 31byte-oriented channels when appropriate. Calling 32:cpp:func:`Channel::IgnoreDatagramBoundaries` on a datagram channel returns a 33byte channel reference to it. The byte view of the channel is simply the 34concatenation of the contents of the datagrams. 35 36This is only valid if, for the datagram channel: 37 38- datagram boundaries have no significance or meaning, 39- zero-length datagrams are not used to convey information, since they are 40 meaningless for byte channels, 41- short or zero-length writes through the byte API will not result in 42 unacceptable overhead. 43 44------------- 45API reference 46------------- 47.. doxygengroup:: pw_channel 48 :content-only: 49 :members: 50 51Channel implementations 52======================= 53.. doxygengroup:: pw_channel_forwarding 54 :content-only: 55 :members: 56 57.. doxygengroup:: pw_channel_loopback 58 :content-only: 59 :members: 60 61.. doxygengroup:: pw_channel_epoll 62 :content-only: 63 :members: 64