From 108338207b855eb08f72376f746b133e91614dd4 Mon Sep 17 00:00:00 2001 From: Christiano Haesbaert Date: Sun, 1 Dec 2024 22:50:48 +0100 Subject: [PATCH] HTML bits for quark_queue_get_event(3) --- docs/index.html | 42 ++++++++-------- docs/quark-btf.8.html | 4 +- docs/quark-mon.8.html | 4 +- docs/quark-test.8.html | 4 +- docs/quark.7.html | 42 ++++++++-------- docs/quark_event_dump.3.html | 4 +- docs/quark_process_lookup.3.html | 6 +-- docs/quark_queue_block.3.html | 8 +-- docs/quark_queue_close.3.html | 4 +- docs/quark_queue_default_attr.3.html | 4 +- docs/quark_queue_get_epollfd.3.html | 8 +-- ...ts.3.html => quark_queue_get_event.3.html} | 49 +++++++++---------- docs/quark_queue_get_stats.3.html | 6 +-- docs/quark_queue_open.3.html | 8 +-- 14 files changed, 92 insertions(+), 101 deletions(-) rename docs/{quark_queue_get_events.3.html => quark_queue_get_event.3.html} (83%) diff --git a/docs/index.html b/docs/index.html index 3e5f973..ac8a0fe 100644 --- a/docs/index.html +++ b/docs/index.html @@ -289,9 +289,9 @@

quark_queue_get_events(3). + quark_queue_get_event(3).
  • No threads are created, the library is driven solely through - quark_queue_get_events(3).
    • + quark_queue_get_event(3).
  • Access to a quark_queue must be synchronized by the user in the case of multithreading.
    • @@ -307,10 +307,10 @@

    quark_queue_close(3) on exit.

    -

    quark_queue_get_events(3) +

    quark_queue_get_event(3) is the main driver of the library, it does the buffering, per-ring scanning, - aggregation and event cache garbage collecting. In case there are no events - it returns zero and the user is expected to call + aggregation and event cache garbage collection. In case there are no events + it returns NULL and the user is expected to call quark_queue_block(3) or equivalent.

    @@ -324,24 +324,22 @@

    < int main(void) { - struct quark_queue qq; - struct quark_event qevs[32], *qev; - int n, i; + struct quark_queue qq; + const struct quark_event *qev; if (quark_queue_open(&qq, NULL) == -1) err(1, "quark_queue_open"); for (; ;) { - n = quark_queue_get_events(&qq, qevs, 32); - if (n == -1) { - warn("quark_queue_get_events"); - break; + qev = quark_queue_get_event(&qq); + + /* No events, just block */ + if (qev == NULL) { + quark_queue_block(qq); + continue; } - /* Scan each event */ - for (i = 0, qev = qevs; i < n; i++, qev++) - quark_event_dump(qev, stdout); - if (n == 0) - quark_queue_block(&qq); + + quark_event_dump(qev, stdout); } quark_queue_close(&qq); @@ -358,8 +356,8 @@

    quark_queue_default_attr(3)
    get default attributes of quark_queue_open(3).
    -
    quark_queue_get_events(3)
    -
    get events, main library call.
    +
    quark_queue_get_event(3)
    +
    get event, main library call.
    quark_process_lookup(3)
    lookup a process in quark's internal cache
    quark_event_dump(3)
    @@ -377,7 +375,7 @@

    -

    quark_queue_get_events(3) +

    quark_queue_get_event(3) is the meat of the library and contains further useful documentation.

    quark-mon(8) is the easiest way to get started with quark.

    @@ -392,7 +390,7 @@

    quark_queue_block(3), quark_queue_close(3), quark_queue_get_epollfd(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark-btf(8), @@ -411,7 +409,7 @@

    - +
    November 12, 2024December 1, 2024 Linux
    diff --git a/docs/quark-btf.8.html b/docs/quark-btf.8.html index 05c6a8e..0c7413d 100644 --- a/docs/quark-btf.8.html +++ b/docs/quark-btf.8.html @@ -157,7 +157,7 @@

    quark_queue_block(3), quark_queue_close(3), quark_queue_get_epollfd(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark-mon(8)

    @@ -165,7 +165,7 @@

    quark_queue_block(3), quark_queue_close(3), quark_queue_get_epollfd(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark-btf(8), @@ -180,7 +180,7 @@

    quark_queue_block(3), quark_queue_close(3), quark_queue_get_epollfd(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark-btf(8), @@ -129,7 +129,7 @@

    quark_queue_get_events(3). + quark_queue_get_event(3).
  • No threads are created, the library is driven solely through - quark_queue_get_events(3).
    • + quark_queue_get_event(3).
  • Access to a quark_queue must be synchronized by the user in the case of multithreading.
    • @@ -307,10 +307,10 @@

    quark_queue_close(3) on exit.

    -

    quark_queue_get_events(3) +

    quark_queue_get_event(3) is the main driver of the library, it does the buffering, per-ring scanning, - aggregation and event cache garbage collecting. In case there are no events - it returns zero and the user is expected to call + aggregation and event cache garbage collection. In case there are no events + it returns NULL and the user is expected to call quark_queue_block(3) or equivalent.

    @@ -324,24 +324,22 @@

    < int main(void) { - struct quark_queue qq; - struct quark_event qevs[32], *qev; - int n, i; + struct quark_queue qq; + const struct quark_event *qev; if (quark_queue_open(&qq, NULL) == -1) err(1, "quark_queue_open"); for (; ;) { - n = quark_queue_get_events(&qq, qevs, 32); - if (n == -1) { - warn("quark_queue_get_events"); - break; + qev = quark_queue_get_event(&qq); + + /* No events, just block */ + if (qev == NULL) { + quark_queue_block(qq); + continue; } - /* Scan each event */ - for (i = 0, qev = qevs; i < n; i++, qev++) - quark_event_dump(qev, stdout); - if (n == 0) - quark_queue_block(&qq); + + quark_event_dump(qev, stdout); } quark_queue_close(&qq); @@ -358,8 +356,8 @@

    quark_queue_default_attr(3)
    get default attributes of quark_queue_open(3).
    -
    quark_queue_get_events(3)
    -
    get events, main library call.
    +
    quark_queue_get_event(3)
    +
    get event, main library call.
    quark_process_lookup(3)
    lookup a process in quark's internal cache
    quark_event_dump(3)
    @@ -377,7 +375,7 @@

    -

    quark_queue_get_events(3) +

    quark_queue_get_event(3) is the meat of the library and contains further useful documentation.

    quark-mon(8) is the easiest way to get started with quark.

    @@ -392,7 +390,7 @@

    quark_queue_block(3), quark_queue_close(3), quark_queue_get_epollfd(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark-btf(8), @@ -411,7 +409,7 @@

    - +
    November 12, 2024December 1, 2024 Linux
    diff --git a/docs/quark_event_dump.3.html b/docs/quark_event_dump.3.html index 1927d8a..1423f95 100644 --- a/docs/quark_event_dump.3.html +++ b/docs/quark_event_dump.3.html @@ -98,7 +98,7 @@

    quark_queue_close(3), quark_queue_default_attr(3), quark_queue_get_epollfd(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark(7), @@ -108,7 +108,7 @@

    be modified, or accessed while - quark_queue_get_events(3) + quark_queue_get_event(3) is taking place, as this might free the pointed memory.

    @@ -56,7 +56,7 @@

    quark_queue_close(3), quark_queue_default_attr(3), quark_queue_get_epollfd(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark-btf(8), @@ -66,7 +66,7 @@

    <

    quark_queue_block blocks the calling process until there would be events to be read with - quark_queue_get_events(3). + quark_queue_get_event(3).

    Internally this will call epoll_wait(2) on the descriptor returned by @@ -41,7 +41,7 @@

    quark_queue_get_events(3) + quark_queue_get_event(3) until it returns zero, signifying there are no more events to be read. See quark(7) for an example.

    @@ -58,7 +58,7 @@

    quark_queue_close(3), quark_queue_default_attr(3), quark_queue_get_epollfd(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark(7), @@ -69,7 +69,7 @@

    quark_queue_block(3), quark_queue_default_attr(3), quark_queue_get_epollfd(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark(7), @@ -59,7 +59,7 @@

    quark_process_lookup(3), quark_queue_block(3), quark_queue_close(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_open(3), quark(7), quark-btf(8), @@ -53,7 +53,7 @@

    quark_queue_get_events(3) - to fetch the expired events.

    + quark_queue_get_event(3) + to fetch the expired event.

    @@ -82,7 +82,7 @@

    quark_queue_block(3), quark_queue_close(3), quark_queue_default_attr(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark(7), @@ -93,7 +93,7 @@

    -

    quark_queue_get_events — +

    quark_queue_get_event — main quark driver

    #include <quark.h>

    -

    int +

    const struct quark_event *
    - quark_queue_get_events(struct - quark_queue *qq, struct - quark_event *qev, int - nqev);

    + quark_queue_get_event(struct + quark_queue *qq);

    -quark_queue_get_events fills the array of events pointed - to by qev to a maximum of neqv - entries. +quark_queue_get_event returns a pointer to the next + quark_event, or NULL if there isn't any.

    This function is the main driver of quark. Quark doesn't create threads or introduces hidden control flows, all its state is mutated through this function call. For a better explanation of quark's design, refer to @@ -45,10 +42,10 @@

  • -

    process points to internal data, it +

    The returned quark_event pointer as well as + the process member point to internal data, they - be modified and/or stored. In the case of multithreading, the pointer should - not be accessed concurrently with another thread which executes - quark_queue_get_events.

    + be modified and/or stored. In the case of multithreading, the pointers + should not be accessed concurrently with another running + quark_queue_get_event.

    In other words, read the stuff you want, copy it out, and forget about it.

    -

    The number of filled events via qev to a - maximum of nqev. If zero is returned, the user should - consider calling - quark_queue_block(3). In - the case of an internal error, -1 is returned and - errno is set.

    +

    A pointer to quark_event. If there aren't + events, NULL is returned and the user should consider calling + quark_queue_block(3).

    • A a counter of missed backend events. This can happen if the user didn't call - quark_queue_get_events(3) + quark_queue_get_event(3) fast enough or if simply can't handle the load, the former is way more likely. It is a state @@ -80,7 +80,7 @@

    quark_queue_block(3), quark_queue_close(3), quark_queue_default_attr(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_open(3), quark(7), quark-btf(8), @@ -90,7 +90,7 @@

    quark_queue_get_events(3) + quark_queue_get_event(3) with the events member set to QUARK_EV_SNAPSHOT. @@ -132,7 +132,7 @@

    How long to buffer (hold) an event before delivering it to the user via - quark_queue_get_events(3). + quark_queue_get_event(3).

    Events received from the backend are not immediately forwarded to the user, this allows multiple events to be aggregated as well as ordered by time. In case quark is overloaded, it will use a stepping @@ -159,7 +159,7 @@

    quark_queue_close(3), quark_queue_default_attr(3), quark_queue_get_epollfd(3), - quark_queue_get_events(3), + quark_queue_get_event(3), quark_queue_get_stats(3), quark(7), quark-btf(8), @@ -169,7 +169,7 @@