What is a 'slot' in sd-bus (C language)

Question

There are several APIs in systemd's sd-bus.h file which optionally take a slot argument. Here's some examples:

int sd_bus_call_async(sd_bus *bus, sd_bus_slot **slot, sd_bus_message *m, sd_bus_message_handler_t callback, void *userdata, uint64_t usec);
int sd_bus_add_filter(sd_bus *bus, sd_bus_slot **slot, sd_bus_message_handler_t callback, void *userdata);
int sd_bus_add_fallback(sd_bus *bus, sd_bus_slot **slot, const char *prefix, sd_bus_message_handler_t callback, void *userdata);

If the calling code specifies NULL then it becomes a "floating slot" which I guess means the calling code doesn't need to worry about it.

Most of the example source code I see out there is like this example project: https://github.com/tasleson/dbus-signals/blob/6d0e43d02d24ed51a17ce7df15a3a0a64ec0170d/spamsignals.c#L160

It takes a slot, and then sometime later it unreferences the slot. But it doesn't actually do anything with it.

Answer 1

Federico is correct, but perhaps more detail would help? The slot is essentially an opaque handle that lets you manage the life-cycle of the object that you are attaching to your sd_bus handle (a vtable, match rule, filter, etc). This is useful when you want to add something and then later remove it.

If the object that you are adding will remain for the lifetime of your process and/or the sd_bus handle you attach it to, then you should probably pass NULL.

Answer 2

Passing your own slot makes your sd-bus-match life being entangled to the one of the slot. This way, when you unreference the slot, you are also destroying the match.
Otherwise, passing NULL will bound your match's life to the one of bus object itself.
The same goes for other functions you listed:
* sd_bus_call_async with a slot gives you the option to destroy the async call by unreferencing the slot.
*sd_bus_add_filter with a slot will destroy the filter when you unreference the slot.
I am not sure about sd_bus_add_fallback because i never heard about it though.
Check here for function being called when slot gets unreferenced: https://github.com/systemd/systemd/blob/a7753693547233e4a1d6e10b1a8f6515a477f227/src/libsystemd/sd-bus/bus-slot.c#L68