callback_profiler.h File Reference

⏱️ Profiling instrumentation for libwebsockets callbacks More...

Go to the source code of this file.

Data Structures
struct	lws_callback_stats_t
	Callback profiling statistics for a single LWS callback reason. More...

Functions
bool	lws_profiler_init (void)
	Initialize the callback profiler.
void	lws_profiler_destroy (void)
	Cleanup the callback profiler.
uint64_t	lws_profiler_start (int callback_reason, uint32_t client_id)
	Record a callback invocation with timing.
void	lws_profiler_stop (uint64_t handle, size_t bytes_processed)
	Stop timing a callback invocation.
bool	lws_profiler_get_stats (int callback_reason, lws_callback_stats_t *stats)
	Get statistics for a specific callback.
void	lws_profiler_reset (void)
	Reset all profiling statistics.
void	lws_profiler_dump_report (void)
	Print profiling report to logs.
char *	lws_profiler_export_json (void)
	Export statistics as JSON.
bool	lws_profiler_is_initialized (void)
	Check if profiler is initialized.

Detailed Description

⏱️ Profiling instrumentation for libwebsockets callbacks

Tracks callback frequency, execution time, and data throughput for performance analysis and optimization.

Features:

• Per-callback statistics (execution time, frequency, data processed)
• Thread-safe counters with minimal overhead
• Min/max/average timing aggregation
• JSON reporting for analysis

Author

Claude (asciichat/polecats/furiosa)

Date

February 2026

Definition in file callback_profiler.h.

Function Documentation

lws_profiler_destroy()

void lws_profiler_destroy

(

void

)

Cleanup the callback profiler.

Frees all profiling structures and destroys mutex. Called at application exit or when stopping profiling.

lws_profiler_dump_report()

void lws_profiler_dump_report

(

void

)

Print profiling report to logs.

Generates a human-readable summary of callback statistics including:

• Invocation frequency per callback type
• Average/min/max execution times
• Total data processed
• Efficiency metrics

lws_profiler_export_json()

char * lws_profiler_export_json

(

void

)

Export statistics as JSON.

Returns a JSON string with complete profiling data. Caller must free the returned string.

Returns

Allocated JSON string, or NULL on failure

lws_profiler_get_stats()

bool lws_profiler_get_stats	(	int	callback_reason,
		lws_callback_stats_t *	stats
	)

Get statistics for a specific callback.

Retrieves accumulated statistics for analysis and logging.

Parameters

callback_reason	LWS callback reason enum (as integer)
stats	Output structure (caller-allocated)

Returns

true if statistics exist, false if callback never invoked

lws_profiler_init()

bool lws_profiler_init

(

void

)

Initialize the callback profiler.

Must be called once at application startup before any callbacks are profiled. Thread-safe operation is ensured via internal mutex.

Returns

true on success, false on failure

lws_profiler_is_initialized()

bool lws_profiler_is_initialized

(

void

)

Check if profiler is initialized.

Returns

true if profiler is active, false otherwise

lws_profiler_reset()

void lws_profiler_reset

(

void

)

Reset all profiling statistics.

Clears counters and timing data. Useful for collecting data over specific time windows.

lws_profiler_start()

uint64_t lws_profiler_start	(	int	callback_reason,
		uint32_t	client_id
	)

Record a callback invocation with timing.

Call this when entering a callback to start timing. Returns an opaque handle used to stop timing.

Parameters

callback_reason	LWS callback reason enum (as integer)
client_id	Optional client identifier for per-client analysis

Returns

Opaque timing handle (non-zero if profiler is initialized)

lws_profiler_stop()

void lws_profiler_stop	(	uint64_t	handle,
		size_t	bytes_processed
	)

Stop timing a callback invocation.

Call this when exiting a callback to record execution time. Updates min/max/average statistics and invocation count.

Parameters

handle	Timing handle returned by lws_profiler_start()
bytes_processed	Bytes processed by this callback (0 if not applicable)