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

From: David Marchand <david.marchand@redhat.com>
To: "Mattias Rönnblom" <mattias.ronnblom@ericsson.com>
Cc: dev@dpdk.org, Jerin Jacob <jerinj@marvell.com>,
	techboard@dpdk.org,  harry.van.haaren@intel.com,
	hofors@lysator.liu.se,
	 Peter Nilsson <peter.j.nilsson@ericsson.com>,
	Heng Wang <heng.wang@ericsson.com>,
	 Naga Harish K S V <s.v.naga.harish.k@intel.com>,
	Pavan Nikhilesh <pbhagavatula@marvell.com>,
	 Gujjar Abhinandan S <abhinandan.gujjar@intel.com>,
	 Erik Gabriel Carrillo <erik.g.carrillo@intel.com>,
	Shijith Thotton <sthotton@marvell.com>,
	 Hemant Agrawal <hemant.agrawal@nxp.com>,
	Sachin Saxena <sachin.saxena@oss.nxp.com>,
	 Liang Ma <liangma@liangbit.com>,
	Peter Mccarthy <peter.mccarthy@intel.com>,
	 Zhirun Yan <zhirun.yan@intel.com>
Subject: Re: [PATCH v6 3/3] doc: add dispatcher programming guide
Date: Tue, 10 Oct 2023 15:31:38 +0200	[thread overview]
Message-ID: <CAJFAV8wOgAH-idcx=pUiBjYhJuc5cQE0y8czPuhd1F1NG0ymqw@mail.gmail.com> (raw)
In-Reply-To: <20231009181711.440865-4-mattias.ronnblom@ericsson.com>

On Mon, Oct 9, 2023 at 8:23 PM Mattias Rönnblom
<mattias.ronnblom@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*

[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?

-- 
David Marchand