TLSPOOL_ASYNC_CANCEL(3)

📦 version 0.9.7, in nixos 26.05

okay so bestie, you just opened TLSPOOL_ASYNC_CANCEL(3) from the Library Calls section, and we're about to get into tlspool_async_cancel — the function that is lowkey a cautionary tale 💅

✨ NAME ✨

tlspool_async_cancel — cancel an asynchronous request to the TLS Pool.

🎀 SYNOPSIS 🎀

#include <stdbool.h>

#include <tlspool/async.h>

bool tlspool_async_cancel (
       struct tlspool_async_pool *pool,
       struct tlspool_async_request *reqcb);

🌸 DESCRIPTION 🌸

Okay so tlspool_async_cancel() retracts a command request from the TLS Pool. And like… this is not generally safe. The TLS Pool will respond with the request identifier of the request at some future date, and when a new request has been assigned the same value, it might... backfire. No cap, that is the actual tea 😭

A more reliable approach is to use tlspool_async_close() for all pending requests at once, and close the socket to the TLS Pool before or during that process. This however is course-grained, if TLS Pool connections are not pooled with a matching logic. Closing down everything is not an option when a single connection is closed down, for example.

The reason for wanting to cancel a request is usually to cleanup resources. The memory for the reqcb and the command in it needs to be cleaned up by the application, and deferral may not be a helpful option; many other resources could be hanging in on the request, waiting for it to be closed. 💀

A better solution may be to replace the callback function registered in the reqcb using an (atomic!) swap of this pointer. The new callback may take care of the (remaining) cleanup as soon as the call to tlspool_async_cancel() returns success. Or much simpler, one might add a flag in the data to indicate that the registered callback function needs to take a diversion. 🦋

The replacement code might for instance be used to simply deallocate the request and command, but otherwise it is left in the pool to lock the request identifier until the TLS Pool returns it. And when the memory is allocated in a memory pool, it might help to simply lower its use count and trigger automatic cleanup with just a small delay until the TLS Pool responds. Slay for delayed cleanup, honestly ✨

To be quite clear, the only reliable use of tlspool_async_cancel() is as a place to find these alternative approaches; do not consider using the call itself... periodt 💅

🌈 ASYNCHRONOUS AND EVENT-DRIVEN USE 🌈

See the other commands, they are more interesting and more useful. fr fr 🫶

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

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

source/version: ARPA2.net · date: March 2019 — stay hydrated, don't cancel unsafely, and remember: this page is iconic for telling you not to use it 😭💖👑

📦 where this page comes from