TLSPOOL_ASYNC_REQUEST(3)

📦 version 0.9.7, in nixos 26.05

💅 tlspool_async_request — the girlies of Library Calls said "send it" 💅

okay bestie, buckle up, because this is the tlspool_async_request(3) page and honestly? she's a baddie. ✨

🌸 NAME 🌸

tlspool_async_request — sends an asynchronous request to the TLS Pool. that's it, that's the vibe. 🫶

🎀 SYNOPSIS 🎀

#include <stdbool.h>

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

bool tlspool_async_request (
       struct tlspool_async_pool *pool,
       struct tlspool_async_request *reqcb,
       int opt_fd);

like, three arguments. she's low maintenance. icon behavior. 👑

💖 DESCRIPTION 💖

tlspool_async_request() takes a command you've already prepped and submits it to the TLS Pool, and registers a callback function that gets invoked when the matching response shows up. no cap. 🦋

⚠️ quick vibe check first: the link to the TLS Pool has to have been set up in pool by a call to tlspool_async_open() before this. otherwise she's not gonna know who she's talking to, and that's awkward.

✨ the file descriptor moment (main character energy) ✨

the most interesting bit of magic happens when opt_fd passes a file descriptor — like a socket — to the TLS Pool. the way this works is, it's recognised by a non-negative value, and it passes along the request's command as ancillary data, across process boundaries. 🧚

this is general POSIX functionality, though not commonly used. iykyk.

the file descriptor arriving at the TLS Pool may be compared to a dup(2) that happens to end up in another process. the local file descriptor remains open, but will usually be closed by the caller. it is safe to do this immediately after the call to tlspool_async_request() — but it is also possible to keep it until a reply comes, and perhaps use dup2(2) to close the old file descriptor and replace it with another with the same number. you can have a completely cool API that does not change the file descriptor number but simply switches on TLS. 💅

💀 but bestie, listen to me on this one: this is only possible when the original file descriptor is still open, as its number might otherwise be reused and replacing its contents might surrender an arbitrary other user's connection! like, that's somebody else's whole session. not iconic. not slay.

🎀 the event loop tea 🎀

take note however that event loops are based on calls such as select(2) or poll(2) and not all such routines are transparent about duplicate handles. the provider of your event loop may be able to explain this with a staggering amount of detail. 😭

🌈 request identifiers 🌈

requests over the link in pool are identified by their pio_reqid, short for its request identifier, and created at random as part of the tlspool_async_request() call. she's unique, she's random, she's fr fr doing the most. ⭐

🦋 the reqcb fields 🦋

the fields in the reqcb structure are:

  • the cmd, holding the TLS Pool command structure
  • and, most importantly, the callback function, with prototype:
void (*cbfunc) (
       struct tlspool_async_request *cbdata,
       int opt_fd);

when it is called, the cbdata parameter will be the original reqcb supplied to tlspool_async_request() and the opt_fd may be supplied by the TLS Pool to commands that expect to receive one. it's another one of those process-crossing file descriptor duplications. 🫶

🧚 ASYNCHRONOUS AND EVENT-DRIVEN USE 🧚

the call to tlspool_async_request() returns immediately, and when successful the registered callback will later be called, normally as part of a tlspool_async_process() run. 🌸

there is no thread or process responsible of doing this; the call to tlspool_async_process() must be driven by the application. yes, that means you. you're the main character here, bestie. 👑

the asynchronous API never allocates memory. the reqcb structure needs to be allocated by the caller and cannot be removed until either tlspool_async_cancel() or tlspool_async_close() cancels this pending request.

the application may change its mind and want to retract a command, but the TLS Pool will not be notified and may still respond with the request identifier. 😭 this introduces a risk in terms of stability. having said that, the tlspool_async_cancel() operation is the call that retracts the command and allows the memory of the reqcb to return to its caller. so like, that's your move.

✨ RETURN VALUE ✨

the function returns true on success or, in case of failure, it returns false and sets errno appropriately. classic. 🎀

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.

🌈 ERRORS 🌈

none known to date. 💀 she's clean, she's pristine, no drama on record (yet).

💜 AUTHOR 💜

written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project. 🫶

🐛 REPORTING BUGS 🐛

for any discussion, including about bugs, please use the mailing list found on http://lists.arpa2.org/mailman/listinfo/tls-pool.

please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon implementation status. 📚

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. ✨

okay that's the whole page, you ate that. 🍓 go forth and be asynchronous. 💅

~ ARPA2.net, March 2019 ~ 🎀 mwah, catch u in the next manpage bestie 💖

📦 where this page comes from