named.h File Reference

Named object registry for debugging — log identifiable resource names. More...

Go to the source code of this file.

Data Structures
struct	named_metadata_t
	The useful part of named metadata is in its fields: together they describe what is pending, who owns it, and how much data is valid. Keep the object with its parent operation and use the parent cleanup path. More...

Macros
#define	DEBUG_NAMED_NAME_BUFFER_SIZE   256
#define	DEBUG_NAMED_TYPE_BUFFER_SIZE   64
#define	DEBUG_NAMED_FORMAT_BUFFER_SIZE   64
#define	NAMED_REGISTER(ptr, name, type, fmt, parent_ptr)
	Register any pointer with base name, type, format spec, and location (auto-suffix).
#define	NAMED_REGISTER_FMT(ptr, type, fmt_spec, fmt, ...)
	Register with a formatted name, type, and format spec.
#define	NAMED_UNREGISTER(ptr)
	Unregister a pointer.
#define	NAMED_GET(ptr)
	Look up registered name for a pointer.
#define	NAMED_DESCRIBE(ptr, hint)
	Describe a pointer in log format.
#define	NAMED_REGISTER_ID(id, name, type, fmt, parent_ptr)
	Register an integer handle (fd, socket, etc.) with type.
#define	NAMED_UNREGISTER_ID(id)
	Unregister an integer handle.
#define	NAMED_DESCRIBE_ID(id, hint)
	Describe an integer handle in log format.
#define	NAMED_REGISTER_MUTEX(mutex, name, parent_ptr)
	Register a mutex with automatic format specifier.
#define	NAMED_REGISTER_RWLOCK(lock, name, parent_ptr)
	Register an rwlock with automatic format specifier.
#define	NAMED_REGISTER_COND(cond, name, parent_ptr)
	Register a condition variable with automatic format specifier.
#define	NAMED_REGISTER_SOCKET(socket, name, parent_ptr)
	Register a socket with automatic format specifier.
#define	NAMED_UNREGISTER_SOCKET(socket)
#define	NAMED_REGISTER_WEBSOCKET(websocket, name, parent_ptr)
	Register a WebSocket connection with automatic format specifier.
#define	NAMED_REGISTER_DATACHANNEL(datachannel, name, parent_ptr)
	Register a data channel with automatic format specifier.
#define	NAMED_REGISTER_THREADPOOL_WORK(work, name, parent_ptr)
	Register a thread pool work item with automatic format specifier.
#define	NAMED_REGISTER_CLIENT(client, name, parent_ptr)
	Register a client connection with automatic format specifier.
#define	NAMED_REGISTER_CRYPTO_CONTEXT(ctx, name, parent_ptr)
	Register a crypto context with automatic format specifier.
#define	NAMED_REGISTER_TRANSPORT(transport, name, parent_ptr)
	Register a transport with automatic format specifier.
#define	NAMED_REGISTER_FRAME_BUFFER(buf, name, parent_ptr)
	Register a frame buffer with automatic format specifier.
#define	NAMED_REGISTER_PACKET_QUEUE(queue, name, parent_ptr)
	Register a packet queue with automatic format specifier.
#define	NAMED_REGISTER_AUDIO_RINGBUF(buf, name, parent_ptr)
	Register an audio ring buffer with automatic format specifier.
#define	NAMED_REGISTER_MIXER(mixer, name, parent_ptr)
	Register an audio mixer with automatic format specifier.
#define	NAMED_REGISTER_AUDIO_CODEC(codec, name, parent_ptr)
	Register an audio codec with automatic format specifier.
#define	NAMED_REGISTER_VIDEO_ENCODER(encoder, name, parent_ptr)
	Register a video encoder with automatic format specifier.
#define	NAMED_REGISTER_BUFFER_DOMAIN(pool, name, parent_ptr)
	Register a buffer domain with automatic format specifier.
#define	NAMED_REGISTER_FFMPEG_DECODER(decoder, name, parent_ptr)
	Register an FFmpeg decoder with automatic format specifier.
#define	NAMED_REGISTER_FFMPEG_ENCODER(encoder, name, parent_ptr)
	Register an FFmpeg encoder with automatic format specifier.
#define	NAMED_REGISTER_H265_ENCODER(encoder, name, parent_ptr)
	Register an H.265 encoder with automatic format specifier.
#define	NAMED_REGISTER_H265_DECODER(decoder, name, parent_ptr)
	Register an H.265 decoder with automatic format specifier.
#define	NAMED_REGISTER_AUDIO_CONTEXT(ctx, name, parent_ptr)
	Register an audio context with automatic format specifier.
#define	NAMED_REGISTER_RATE_LIMITER(limiter, name, parent_ptr)
	Register a rate limiter with automatic format specifier.
#define	NAMED_REGISTER_WAV_WRITER(writer, name, parent_ptr)
	Register a WAV writer with automatic format specifier.
#define	NAMED_REGISTER_MEDIA_SOURCE(source, name, parent_ptr)
	Register a media source with automatic format specifier.
#define	NAMED_OPEN(pathname, name, flags, ...)
	Open a file and register the file descriptor.
#define	NAMED_UNREGISTER_FD(fd)
	Unregister a file descriptor.
#define	NAMED_REGISTER_FD(fd, name)
	Register an existing file descriptor.
#define	NAMED_REGISTER_ATOMIC(a, name, parent_ptr)
	Register an atomic_t with automatic format specifier.
#define	NAMED_REGISTER_ATOMIC_PTR(a, name, parent_ptr)
	Register an _Atomic(void *) with automatic format specifier.
#define	NAMED_REGISTER_THREAD(thread, name, parent_ptr)
	Register a thread handle with name and automatic format specifier.
#define	NAMED_UNREGISTER_THREAD(thread)
	Unregister a thread handle.
#define	NAMED_REGISTER_TCP_CLIENT(client, name, parent_ptr)
	Register a TCP client with automatic format specifier.
#define	NAMED_REGISTER_WEBSOCKET_CLIENT(client, name, parent_ptr)
	Register a WebSocket client with automatic format specifier.
#define	NAMED_REGISTER_APP_CLIENT(client, name, parent_ptr)
	Register an app client with automatic format specifier.
#define	NAMED_REGISTER_VIDEO_FRAME_BUFFER(buf, name, parent_ptr)
	Register a video frame buffer with automatic format specifier.
#define	NAMED_REGISTER_THREAD_POOL(pool, name, parent_ptr)
	Register a thread pool with automatic format specifier.
#define	NAMED_REGISTER_OPTIONS_BUILDER(builder, name, parent_ptr)
	Register an options builder with automatic format specifier.
#define	NAMED_REGISTER_SIMPLE_FRAME_SWAP(swap, name, parent_ptr)
	Register a simple frame swap with automatic format specifier.
#define	NAMED_REGISTER_CLIENT_AUDIO_PIPELINE(pipeline, name, parent_ptr)
	Register a client audio pipeline with automatic format specifier.
#define	NAMED_REGISTER_WEBSOCKET_IMPL(data, name, parent_ptr)
#define	NAMED_REGISTER_LWS_CONTEXT(context, name, parent_ptr)
	Register a libwebsockets context with automatic format specifier.
#define	NAMED_REGISTER_FFMPEG_CONTEXT(context, name, parent_ptr)
	Register an FFmpeg decoder context with automatic format specifier.
#define	NAMED_REGISTER_CONTEXT(context, context_type, name, parent_ptr)
	Register a generic context with automatic format specifier.
#define	NAMED_GET_BY_PTR(key, buffer, size)
	Get name of a pointer/key or format as address fallback.
#define	NAMED_GET_BY_INT(id, buffer, size)
	Get name of an integer ID or format as hex fallback.
#define	NAMED_GET_BY_STR(str, buffer, size)
	Copy a string to buffer, with bounds checking.
Type-Specific Description Macros
These macros encapsulate the proper casting and type hint for common types. Use these instead of NAMED_DESCRIBE for better readability and consistency.
#define	NAME_DESCRIBE_MUTEX(m)
	Describe a mutex_t for logging.
#define	NAME_DESCRIBE_RWLOCK(l)
	Describe an rwlock_t for logging.
#define	NAME_DESCRIBE_COND(c)
	Describe a cond_t for logging.
#define	NAME_DESCRIBE_THREAD(t)
	Describe a thread for logging.
#define	NAME_DESCRIBE_TRANSPORT(tr)
	Describe a transport for logging.
#define	NAME_DESCRIBE_SOCKET(fd)
	Describe a socket for logging.
#define	NAME_DESCRIBE_RINGBUF(rb)
	Describe a ring buffer for logging.

Typedefs
typedef void(*	named_iter_callback_t) (uintptr_t key, const char *name, void *user_data)
	Callback function for iterating registered entries.
typedef void(*	named_snapshot_fn) (uintptr_t key, uint64_t generation, const char *name, const char *type, const char *file, int line, void *data)

Functions
asciichat_error_t	named_init (void)
	Initialize the named object registry.
void	named_destroy (void)
	Destroy the named object registry.
const char *	named_register (uintptr_t key, const char *base_name, const char *type, const char *format_spec, const char *file, int line, const char *func, uintptr_t parent_key)
	Register a resource with an auto-suffixed name, type, and location info.
const char *	named_register_fmt (uintptr_t key, const char *type, const char *format_spec, const char *file, int line, const char *func, const char *fmt,...)
	Register a resource with a formatted name, type, and location info (no auto-suffix).
void	named_unregister (uintptr_t key)
	Unregister a resource by key.
const char *	named_update_name (uintptr_t key, const char *new_base_name)
	Update the registered name for a resource with a new base name.
const char *	named_get (uintptr_t key)
	Look up the registered name for a resource.
bool	named_metadata_copy (uintptr_t key, named_metadata_t *output)
bool	named_fd_metadata_copy (int fd, named_metadata_t *output)
bool	named_packet_metadata_copy (int packet_type, named_metadata_t *output)
const char *	named_get_type (uintptr_t key)
	Look up the registered type for a resource.
bool	named_registry_has_type (const char *type, size_t length)
const char *	named_get_format_spec (uintptr_t key)
	Get the format specifier for a registered named object.
const char *	named_register_fd (int fd, const char *name, const char *file, int line, const char *func)
	Register a file descriptor with namespace encoding.
const char *	named_get_fd (int fd)
	Look up a registered file descriptor.
const char *	named_get_fd_format_spec (int fd)
	Get the format specifier for a registered file descriptor.
const char *	named_register_packet_type (int pkt_type, const char *file, int line, const char *func)
	Register a packet type with namespace encoding.
const char *	named_get_packet_type (int pkt_type)
	Look up a registered packet type.
const char *	named_get_packet_type_format_spec (int pkt_type)
	Get the format specifier for a registered packet type.
const char *	named_get_by_type_and_id (const char *type_name, size_t type_len, int id)
	Look up an integer ID by type name and value.
const char *	named_describe (uintptr_t key, const char *type_hint)
	Format a description string for logging.
uintptr_t	thread_to_key (platform_thread_t thread)
	Convert a thread handle to a registry key.
const char *	named_describe_thread (void *thread)
	Describe a thread for logging (function wrapper).
void	named_registry_register_packet_types (void)
	Register all packet types from packet_type_t enum.
asciichat_error_t	named_registry_for_each (named_iter_callback_t callback, void *user_data, bool *completed)
	Iterate through all registered entries.
bool	named_registry_read (uintptr_t key, const char *type, void(*read_object)(uintptr_t, void *), void *user_data)
asciichat_error_t	named_registry_try_snapshot (size_t capacity, size_t *required, bool *completed, named_snapshot_fn copy, void *data)
void	named_print_hash_stats (void)

Detailed Description

Named object registry for debugging — log identifiable resource names.

Definition in file debug/named.h.