[PATCH v6 3/3] doc: add dispatcher programming guide

[Mattias Rönnblom]

On 2023-10-10 15:31, David Marchand wrote:
> On Mon, Oct 9, 2023 at 8:23 PM Mattias Rönnblom
> <mattias.ronnblom at ericsson.com> wrote:
> 
> [snip]
> 
>> +A module may use more than one event handler, for convenience or to
>> +further decouple sub-modules. However, the dispatcher may impose an
>> +upper limit of the number handlers. In addition, installing a large
>> +number of handlers increase dispatcher overhead, although this does
>> +not nessarily translate to a system-level performance degradation. See
> 
> necessarily*
> 

Will fix.

> [snip]
> 
>> +Event Clustering
>> +^^^^^^^^^^^^^^^^
>> +
>> +The dispatcher maintains the order of events destined for the same
>> +handler.
>> +
>> +*Order* here refers to the order in which the events were delivered
>> +from the event device to the dispatcher (i.e., in the event array
>> +populated by ``rte_event_dequeue_burst()``), in relation to the order
>> +in which the dispatcher deliveres these events to the application.
>> +
>> +The dispatcher *does not* guarantee to maintain the order of events
>> +delivered to *different* handlers.
>> +
>> +For example, assume that ``MODULE_A_QUEUE_ID`` expands to the value 0,
>> +and ``MODULE_B_STAGE_0_QUEUE_ID`` expands to the value 1. Then
>> +consider a scenario where the following events are dequeued from the
>> +event device (qid is short for event queue id).
>> +
>> +.. code-block::
> 
> Surprisingly, Ubuntu in GHA sphinx complains about this code-block
> directive while generating on my Fedora runs fine...
> 
> FAILED: doc/guides/html
> /usr/bin/python3 ../buildtools/call-sphinx-build.py
> /usr/bin/sphinx-build 23.11.0-rc0
> /home/runner/work/dpdk/dpdk/doc/guides
> /home/runner/work/dpdk/dpdk/build/doc/guides -a -W
> 
> Warning, treated as error:
> /home/runner/work/dpdk/dpdk/doc/guides/prog_guide/dispatcher_lib.rst:253:Error
> in "code-block" directive:
> 1 argument(s) required, 0 supplied.
> 
> .. code-block::
> 
>      [e0: qid=1], [e1: qid=1], [e2: qid=0], [e3: qid=1]
> 
> Looking at https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block,
> I suspect there is probably a difference in the default settings of
> sphinx in those Ubuntu containers.
> 
> This is pseudo-code / close to C, so we could probably mark this block
> as "C", but "none" works fine too.
> WDYT?
> 
> 

I'm also running Ubuntu, and thus didn't experience this issue.

"none" seems better to me, to avoid potential future failures of syntax 
highlighting.

Thanks!