1.. _module-pw_channel-quickstart-guides: 2 3=================== 4Quickstart & guides 5=================== 6.. pigweed-module-subpage:: 7 :name: pw_channel 8 9.. _module-pw_channel-guides-faqs: 10 11--------------------------------- 12Frequently asked questions (FAQs) 13--------------------------------- 14 15My API reads and writes data. Should I implement the ``Channel`` interface, or should my API accept a ``Channel`` to read from and write into? 16============================================================================================================================================== 17Users should typically only implement the ``Channel`` interface themselves if 18they want to control where buffers for underlying data are stored. 19 20On the read side, the channel implementation controls buffer allocation by 21choosing how to allocate the ``MultiBuf`` values that are returned from 22``PendRead``. 23 24On the write side, the channel implementation controls buffer allocation via 25its implementation of the ``PendAllocateWriteBuffer`` method. 26 27Most commonly, lower layers of the communications stack implement ``Channel`` in 28order to provide buffers that are customized to the needs of the underlying 29transport. For example, a UART DMA channel might need to allocate buffers 30out of particular DMA-compatible memory regions, with a particular alignment, 31or of a particular MTU size. 32 33The top-level or application layer should typically work with provided 34channel implementations in order to allow the lower layers to control 35allocation and minimize copies. 36 37Intermediate layers of the stack should generally give preference to 38allowing lower layers of the stack to allocate, and so should implement 39a channel interface for the higher layer by delegating to the lower layer. 40When intermediate layers must copy data (are incompatible with zero-copy), 41they should prefer to accept channels from both the higher and lower 42layers so that both the application layer and lower layers can choose 43how to manage memory allocations. 44 45When necessary, two APIs that accept channels can be paired together 46using a ``ForwardingChannel`` which manages allocations by delegating 47to the provided ``MultiBufAllocator``. 48 49Can different tasks write into and read from the same channel? 50============================================================== 51No; it is not possible to read from the channel in one task while 52writing to it from another task. A single task must own and operate 53the channel. In the future, a wrapper will be offered which will 54allow the channel to be split into a read half and a write half which 55can be used from independent tasks. 56