TLSPOOL_ASYNC_PROCESS(3)

📦 version 0.9.7, in nixos 26.05

💅 TLSPOOL_ASYNC_PROCESS(3) — like, the async processing girlie of the TLS Pool

okay so bestie, welcome to the TLSPOOL_ASYNC_PROCESS page from Library Calls — yes that's the manual section, we're in the big leagues now 🌈. Sit down, grab a strawberry 🍓, and let me tell you about the one function that actually does the work.

✨ NAME ✨

tlspool_async_process — literally the function that processes command responses from the TLS Pool 💖

🎀 SYNOPSIS 🎀

#include <stdbool.h>

#include <tlspool/async.h>
#include <tlspool/commands.h>

bool tlspool_async_process (
       struct tlspool_async_pool *pool);

no cap, that's the whole signature. one arg, one bool back 🫶

🦋 DESCRIPTION 🦋

so tlspool_async_process() attempts to read command responses from the TLS Pool. The socket it uses is non-blocking, which means it's gonna gracefully dip out the second there's no work left to do — no awkward waiting around, she's not that kind of function 💅. The whole idea is: process anything that can be done, usually because an event told you "hey, there's data to read from the TLS Pool socket" ✨.

While it's processing responses, tlspool_async_process() looks up the request identifier in each one, and uses that to find the matching request in the pool — the one that tlspool_async_request() dropped there to wait for this exact response. Then the request gets removed from the pool and its callback function is invoked. bye bestie, you're being called back 👋

Effectively? The task of tlspool_async_process() is to invoke all those callbacks that are ready to continue. And, as is common in both asynchronous and event-driven styles, these functions should not block and should return control sooner rather than later. The responsiveness of an entire application generally relies on this — like, the whole vibe check of your app depends on it 😭.

It should be possible to work in this style without threading or processing. There may be one exception, and that is to fill a multi-core processor with work. In such architectures, it's common to allocate one thread to each core and make them all run such a loop. main character energy per core, honestly 👑

Lowkey important: the asynchronous design of the TLS Pool is not re-entrant, for reasons of simplicity and speed. When a thread is tied to a core and when each connection has its own core, it should be possible to use the TLS Pool without further locking. And experience optimal speed. slay 🔥

⭐ ASYNCHRONOUS AND EVENT-DRIVEN USE ⭐

The call to tlspool_async_process() is one of the rare functions in an asynchronous or event-driven design that may run for a while — because it's effectively pointing the processor core at work that needs to be done, and running through it is actually quite productive 🌸. There is no current support to finish (a bit) earlier, for instance to improve responsiveness to other events calling for attention. ngl, she commits to the bit.

The asynchronous API never allocates memory. By symmetry, tlspool_async_process() does not free any memory either 🙈. It is up to the initiator of the request what to do: return the request memory to a pool, free(3) it, or perhaps recycle it. Or reduce the use count of a memory pool. Whatever it does — keep in mind that some of the data in the command may be private; it probably should not be delivered back into a queue, or even main memory, without clearing it 🧹💀

💜 RETURN VALUE 💜

The function returns true on success or, in case of failure, it returns false and sets errno appropriately. Note that there are local extensions founded in the com_err(3) system. Error codes specific to the TLS Pool are in <tlspool/errortable.h> but other systems may also link in with the com_err(3) error system. iykyk 🎀

💀 ERRORS 💀

None known to date. iconic behaviour, truly no notes 👑

🫶 AUTHOR 🫶

Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project. ty king 🌟

📢 REPORTING BUGS 📢

For any discussion, including about bugs, please use the mailing list found on http://lists.arpa2.org/mailman/listinfo/tls-pool. we're all in the group chat, it's fine 💖

Please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon implementation status. yes, actually read them, bestie 🙏

Copyright © 2015-2019 Rick van Rein, ARPA2.net.

ARPA2 is funded from InternetWide.org, which in turns receives donations from various funding sources with an interest in a private and secure Internet that gives users control over their online presence. This particular project has been sponsored in part by NCSC. 💜

🌈 SEE ALSO 🌈

The configuration file option socket_name influences the path at which the TLS Pool is available; this is not read by the client library, and when it differs from the default path in TLSPOOL_DEFAULT_SOCKET_PATH, this function is used to inform the client library once, before calling any of the other client functions. 🧚

The TLS Pool API is documented in the include file <tlspool/commands.h> and <tlspool/starttls.h> for C, and the tlspool.py module for Python 🐍✨

Online resources may be found on the project home page, http://tlspool.arpa2.net.

aight that's the whole page bestie, go forth and process your async responses 💖

ARPA2.net — March 2019 — and that's the TLSPOOL_ASYNC_PROCESS(3) footer, mwah 😘

📦 where this page comes from