mirror of
https://git.proxmox.com/git/mirror_frr
synced 2025-05-29 18:41:56 +00:00
Merge pull request #13730 from anlancs/doc/thread-event-typo
doc: Adjust event system
This commit is contained in:
commit
e631541b68
@ -46,7 +46,8 @@ implemented in FRR. This doc should be expanded and broken off into its own
|
|||||||
section. For now it provides basic information necessary to understand the
|
section. For now it provides basic information necessary to understand the
|
||||||
interplay between the event system and kernel threads.
|
interplay between the event system and kernel threads.
|
||||||
|
|
||||||
The core event system is implemented in :file:`lib/thread.[ch]`. The primary
|
The core event system is implemented in :file:`lib/event.c` and
|
||||||
|
:file:`lib/frrevent.h`. The primary
|
||||||
structure is ``struct event_loop``, hereafter referred to as a
|
structure is ``struct event_loop``, hereafter referred to as a
|
||||||
``threadmaster``. A ``threadmaster`` is a global state object, or context, that
|
``threadmaster``. A ``threadmaster`` is a global state object, or context, that
|
||||||
holds all the tasks currently pending execution as well as statistics on tasks
|
holds all the tasks currently pending execution as well as statistics on tasks
|
||||||
@ -57,41 +58,41 @@ execute. At initialization, a daemon will typically create one
|
|||||||
fetch each task and execute it.
|
fetch each task and execute it.
|
||||||
|
|
||||||
These tasks have various types corresponding to their general action. The types
|
These tasks have various types corresponding to their general action. The types
|
||||||
are given by integer macros in :file:`event.h` and are:
|
are given by integer macros in :file:`frrevent.h` and are:
|
||||||
|
|
||||||
``THREAD_READ``
|
``EVENT_READ``
|
||||||
Task which waits for a file descriptor to become ready for reading and then
|
Task which waits for a file descriptor to become ready for reading and then
|
||||||
executes.
|
executes.
|
||||||
|
|
||||||
``THREAD_WRITE``
|
``EVENT_WRITE``
|
||||||
Task which waits for a file descriptor to become ready for writing and then
|
Task which waits for a file descriptor to become ready for writing and then
|
||||||
executes.
|
executes.
|
||||||
|
|
||||||
``THREAD_TIMER``
|
``EVENT_TIMER``
|
||||||
Task which executes after a certain amount of time has passed since it was
|
Task which executes after a certain amount of time has passed since it was
|
||||||
scheduled.
|
scheduled.
|
||||||
|
|
||||||
``THREAD_EVENT``
|
``EVENT_EVENT``
|
||||||
Generic task that executes with high priority and carries an arbitrary
|
Generic task that executes with high priority and carries an arbitrary
|
||||||
integer indicating the event type to its handler. These are commonly used to
|
integer indicating the event type to its handler. These are commonly used to
|
||||||
implement the finite state machines typically found in routing protocols.
|
implement the finite state machines typically found in routing protocols.
|
||||||
|
|
||||||
``THREAD_READY``
|
``EVENT_READY``
|
||||||
Type used internally for tasks on the ready queue.
|
Type used internally for tasks on the ready queue.
|
||||||
|
|
||||||
``THREAD_UNUSED``
|
``EVENT_UNUSED``
|
||||||
Type used internally for ``struct event`` objects that aren't being used.
|
Type used internally for ``struct event`` objects that aren't being used.
|
||||||
The event system pools ``struct event`` to avoid heap allocations; this is
|
The event system pools ``struct event`` to avoid heap allocations; this is
|
||||||
the type they have when they're in the pool.
|
the type they have when they're in the pool.
|
||||||
|
|
||||||
``THREAD_EXECUTE``
|
``EVENT_EXECUTE``
|
||||||
Just before a task is run its type is changed to this. This is used to show
|
Just before a task is run its type is changed to this. This is used to show
|
||||||
``X`` as the type in the output of :clicmd:`show thread cpu`.
|
``X`` as the type in the output of :clicmd:`show thread cpu`.
|
||||||
|
|
||||||
The programmer never has to work with these types explicitly. Each type of task
|
The programmer never has to work with these types explicitly. Each type of task
|
||||||
is created and queued via special-purpose functions (actually macros, but
|
is created and queued via special-purpose functions (actually macros, but
|
||||||
irrelevant for the time being) for the specific type. For example, to add a
|
irrelevant for the time being) for the specific type. For example, to add a
|
||||||
``THREAD_READ`` task, you would call
|
``EVENT_READ`` task, you would call
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
@ -113,9 +114,9 @@ sockets needed for peerings or IPC.
|
|||||||
|
|
||||||
To retrieve the next task to run the program calls ``event_fetch()``.
|
To retrieve the next task to run the program calls ``event_fetch()``.
|
||||||
``event_fetch()`` internally computes which task to execute next based on
|
``event_fetch()`` internally computes which task to execute next based on
|
||||||
rudimentary priority logic. Events (type ``THREAD_EVENT``) execute with the
|
rudimentary priority logic. Events (type ``EVENT_EVENT``) execute with the
|
||||||
highest priority, followed by expired timers and finally I/O tasks (type
|
highest priority, followed by expired timers and finally I/O tasks (type
|
||||||
``THREAD_READ`` and ``THREAD_WRITE``). When scheduling a task a function and an
|
``EVENT_READ`` and ``EVENT_WRITE``). When scheduling a task a function and an
|
||||||
arbitrary argument are provided. The task returned from ``event_fetch()`` is
|
arbitrary argument are provided. The task returned from ``event_fetch()`` is
|
||||||
then executed with ``event_call()``.
|
then executed with ``event_call()``.
|
||||||
|
|
||||||
@ -135,23 +136,23 @@ Mapping the general names used in the figure to specific FRR functions:
|
|||||||
|
|
||||||
- ``task`` is ``struct event *``
|
- ``task`` is ``struct event *``
|
||||||
- ``fetch`` is ``event_fetch()``
|
- ``fetch`` is ``event_fetch()``
|
||||||
- ``exec()`` is ``event_call``
|
- ``exec()`` is ``event_call()``
|
||||||
- ``cancel()`` is ``event_cancel()``
|
- ``cancel()`` is ``event_cancel()``
|
||||||
- ``schedule()`` is any of the various task-specific ``event_add_*`` functions
|
- ``schedule()`` is any of the various task-specific ``event_add_*`` functions
|
||||||
|
|
||||||
Adding tasks is done with various task-specific function-like macros. These
|
Adding tasks is done with various task-specific function-like macros. These
|
||||||
macros wrap underlying functions in :file:`thread.c` to provide additional
|
macros wrap underlying functions in :file:`event.c` to provide additional
|
||||||
information added at compile time, such as the line number the task was
|
information added at compile time, such as the line number the task was
|
||||||
scheduled from, that can be accessed at runtime for debugging, logging and
|
scheduled from, that can be accessed at runtime for debugging, logging and
|
||||||
informational purposes. Each task type has its own specific scheduling function
|
informational purposes. Each task type has its own specific scheduling function
|
||||||
that follow the naming convention ``event_add_<type>``; see :file:`event.h`
|
that follow the naming convention ``event_add_<type>``; see :file:`frrevent.h`
|
||||||
for details.
|
for details.
|
||||||
|
|
||||||
There are some gotchas to keep in mind:
|
There are some gotchas to keep in mind:
|
||||||
|
|
||||||
- I/O tasks are keyed off the file descriptor associated with the I/O
|
- I/O tasks are keyed off the file descriptor associated with the I/O
|
||||||
operation. This means that for any given file descriptor, only one of each
|
operation. This means that for any given file descriptor, only one of each
|
||||||
type of I/O task (``THREAD_READ`` and ``THREAD_WRITE``) can be scheduled. For
|
type of I/O task (``EVENT_READ`` and ``EVENT_WRITE``) can be scheduled. For
|
||||||
example, scheduling two write tasks one after the other will overwrite the
|
example, scheduling two write tasks one after the other will overwrite the
|
||||||
first task with the second, resulting in total loss of the first task and
|
first task with the second, resulting in total loss of the first task and
|
||||||
difficult bugs.
|
difficult bugs.
|
||||||
|
Loading…
Reference in New Issue
Block a user