Data Structures
struct	sg_entrypoint

struct	sg_entrypoints

struct	sg_route

struct	sg_router

Typedefs
typedef int(*	sg_entrypoints_iter_cb) (void cls, struct sg_entrypoint entrypoint)

typedef int(*	sg_segments_iter_cb) (void cls, unsigned int index, const char segment)

typedef int(*	sg_vars_iter_cb) (void cls, const char name, const char *val)

typedef void(*	sg_route_cb) (void cls, struct sg_route route)

typedef int(*	sg_routes_iter_cb) (void cls, struct sg_route route)

typedef int(*	sg_router_dispatch_cb) (void cls, const char path, struct sg_route *route)

typedef int(*	sg_router_match_cb) (void cls, struct sg_route route)

Functions
const char *	sg_entrypoint_name (struct sg_entrypoint *entrypoint)

int	sg_entrypoint_set_user_data (struct sg_entrypoint entrypoint, void data)

void *	sg_entrypoint_user_data (struct sg_entrypoint *entrypoint)

struct sg_entrypoints *	sg_entrypoints_new (void) __attribute__((malloc))

void	sg_entrypoints_free (struct sg_entrypoints *entrypoints)

int	sg_entrypoints_add (struct sg_entrypoints entrypoints, const char path, void *user_data)

int	sg_entrypoints_rm (struct sg_entrypoints entrypoints, const char path)

int	sg_entrypoints_iter (struct sg_entrypoints entrypoints, sg_entrypoints_iter_cb cb, void cls)

int	sg_entrypoints_clear (struct sg_entrypoints *entrypoints)

int	sg_entrypoints_find (struct sg_entrypoints entrypoints, struct sg_entrypoint entrypoint, const char path)

void *	sg_route_handle (struct sg_route *route)

void *	sg_route_match (struct sg_route *route)

const char *	sg_route_rawpattern (struct sg_route *route)

char *	sg_route_pattern (struct sg_route *route) __attribute__((malloc))

const char *	sg_route_path (struct sg_route *route)

int	sg_route_segments_iter (struct sg_route route, sg_segments_iter_cb cb, void cls)

int	sg_route_vars_iter (struct sg_route route, sg_vars_iter_cb cb, void cls)

void *	sg_route_user_data (struct sg_route *route)

int	sg_routes_add2 (struct sg_route routes, struct sg_route route, const char pattern, char errmsg, size_t errlen, sg_route_cb cb, void *cls)

bool	sg_routes_add (struct sg_route *routes, const char pattern, sg_route_cb cb, void *cls)

int	sg_routes_rm (struct sg_route *routes, const char pattern)

int	sg_routes_iter (struct sg_route routes, sg_routes_iter_cb cb, void cls)

int	sg_routes_next (struct sg_route **route)

unsigned int	sg_routes_count (struct sg_route *routes)

int	sg_routes_cleanup (struct sg_route **routes)

struct sg_router *	sg_router_new (struct sg_route *routes) __attribute__((malloc))

void	sg_router_free (struct sg_router *router)

int	sg_router_dispatch2 (struct sg_router router, const char path, void user_data, sg_router_dispatch_cb dispatch_cb, void cls, sg_router_match_cb match_cb)

int	sg_router_dispatch (struct sg_router router, const char path, void *user_data)

Detailed Description

High-performance path routing.

Typedef Documentation

◆ sg_entrypoints_iter_cb

typedef int(* sg_entrypoints_iter_cb) (void *cls, struct sg_entrypoint *entrypoint)

Callback signature used by sg_entrypoints_iter() to iterate entry-point items.

Parameters

[out]	cls	User-defined closure.
[out]	entrypoint	Current iterated entry-point.

Return values

0	Success.
E<ERROR>	User-defined error to stop the items iteration.

◆ sg_segments_iter_cb

typedef int(* sg_segments_iter_cb) (void *cls, unsigned int index, const char *segment)

Callback signature used by sg_route_segments_iter() to iterate the path segments.

Parameters

[out]	cls	User-defined closure.
[out]	index	Current iterated item index.
[out]	segment	Current iterated segment.

Return values

0	Success.
E<ERROR>	User-defined error to stop the segments iteration.

◆ sg_vars_iter_cb

typedef int(* sg_vars_iter_cb) (void *cls, const char *name, const char *val)

Callback signature used by sg_route_vars_iter() to iterate the path variables.

Parameters

[out]	cls	User-defined closure.
[out]	name	Current iterated variable name.
[out]	val	Current iterated variable value.

Return values

0	Success.
E<ERROR>	User-defined error to stop the variables iteration.

◆ sg_route_cb

typedef void(* sg_route_cb) (void *cls, struct sg_route *route)

Callback signature used to handle the path routing.

Parameters

[out]	cls	User-defined closure.
[out]	route	Route handle.

◆ sg_routes_iter_cb

typedef int(* sg_routes_iter_cb) (void *cls, struct sg_route *route)

Callback signature used by sg_routes_iter() to iterate route items.

Parameters

[out]	cls	User-defined closure.
[out]	route	Current iterated route.

Return values

0	Success.
E<ERROR>	User-defined error to stop the route items iteration.

◆ sg_router_dispatch_cb

typedef int(* sg_router_dispatch_cb) (void *cls, const char *path, struct sg_route *route)

Callback signature used by sg_router_dispatch2 in the route dispatching loop.

Parameters

[out]	cls	User-defined closure.
[out]	path	Route path as a null-terminated string.
[out]	route	Route handle.

Return values

0	Success.
E<ERROR>	User-defined error to stop the route dispatching loop.

◆ sg_router_match_cb

typedef int(* sg_router_match_cb) (void *cls, struct sg_route *route)

Callback signature used by sg_router_dispatch2 when the path matches the pattern before the route dispatching.

Parameters

[out]	cls	User-defined closure.
[out]	route	Route handle.

Return values

0	Success.
E<ERROR>	User-defined error to stop the route dispatching.

Function Documentation

◆ sg_entrypoint_name()

const char * sg_entrypoint_name ( struct sg_entrypoint * entrypoint )

Returns the name of the entry-point handle entrypoint.

Parameters

[in] entrypoint Entry-point handle.

Returns: Entry-point name as a null-terminated string.

Return values

NULL	If the `entrypoint` is null and set the `errno` to `EINVAL`.

◆ sg_entrypoint_set_user_data()

int sg_entrypoint_set_user_data	(	struct sg_entrypoint *	entrypoint,
		void *	data
	)

Sets user data to the entry-point handle.

Parameters

[in]	entrypoint	Entry-point handle.
[in]	data	User data pointer.

Return values

0	Success.
EINVAL	Invalid argument.

◆ sg_entrypoint_user_data()

void * sg_entrypoint_user_data ( struct sg_entrypoint * entrypoint )

Gets user data from the entry-point handle.

Parameters

[in] entrypoint Entry-point handle.

Returns: User data pointer.

Return values

NULL	If `entrypoint` is null and set the `errno` to `EINVAL`.

Examples: example_entrypoint.c.

◆ sg_entrypoints_new()

struct sg_entrypoints * sg_entrypoints_new ( void )

Creates a new entry-points handle.

Returns: Entry-points handle.

Return values

NULL	If no memory space is available.

Examples: example_entrypoint.c.

◆ sg_entrypoints_free()

void sg_entrypoints_free ( struct sg_entrypoints * entrypoints )

Frees the entry-points handle previously allocated by sg_entrypoints_new().

Parameters

[in] entrypoints Pointer of the entry-points to be freed.

Examples: example_entrypoint.c.

◆ sg_entrypoints_add()

int sg_entrypoints_add	(	struct sg_entrypoints *	entrypoints,
		const char *	path,
		void *	user_data
	)

Adds a new entry-point item to the entry-points entrypoints.

Parameters

[in]	entrypoints	Entry-points handle.
[in]	path	Entry-point path.
[in]	user_data	User data pointer.

Return values

0	Success.
EINVAL	Invalid argument.
ENOMEM	Out of memory.
EALREADY	Entry-point already added.

Examples: example_entrypoint.c.

◆ sg_entrypoints_rm()

int sg_entrypoints_rm	(	struct sg_entrypoints *	entrypoints,
		const char *	path
	)

Removes an entry-point item from the entry-points entrypoints.

Parameters

[in]	entrypoints	Entry-points handle.
[in]	path	Entry-point path to be removed.

Return values

0	Success.
EINVAL	Invalid argument.
ENOMEM	Out of memory.
ENOENT	Entry-point already removed.

◆ sg_entrypoints_iter()

int sg_entrypoints_iter	(	struct sg_entrypoints *	entrypoints,
		sg_entrypoints_iter_cb	cb,
		void *	cls
	)

Iterates over entry-point items.

Parameters

[in]	entrypoints	Entry-points handle.
[in]	cb	Callback to iterate the entry-point items.
[in,out]	cls	User-specified value.

Return values

0	Success.
EINVAL	Invalid argument.

Returns: Callback result when it is different from 0.

◆ sg_entrypoints_clear()

int sg_entrypoints_clear ( struct sg_entrypoints * entrypoints )

Clears all existing entry-point items in the entry-points entrypoints.

Parameters

[in] entrypoints Entry-points handle.

Return values

0	Success.
EINVAL	Invalid argument.

◆ sg_entrypoints_find()

int sg_entrypoints_find	(	struct sg_entrypoints *	entrypoints,
		struct sg_entrypoint **	entrypoint,
		const char *	path
	)

Finds an entry-point item by path.

Parameters

[in]	entrypoints	Entry-points handle.
[in,out]	entrypoint	Pointer of the variable to store the found entry-point.
[in]	path	Entry-point path to be found.

Return values

0	Success.
EINVAL	Invalid argument.
ENOMEM	Out of memory.
ENOENT	Pair not found.

Examples: example_entrypoint.c.

◆ sg_route_handle()

void * sg_route_handle ( struct sg_route * route )

Returns the PCRE2 handle containing the compiled regex code.

Parameters

[in] route Route handle.

Returns: PCRE2 handle containing the compiled regex code.

Return values

NULL	If `route` is null and set the `errno` to `EINVAL`.

◆ sg_route_match()

void * sg_route_match ( struct sg_route * route )

Returns the PCRE2 match data created from the route pattern.

Parameters

[in] route Route handle.

Returns: PCRE2 match data.

Return values

NULL	If `route` is null and set the `errno` to `EINVAL`.

◆ sg_route_rawpattern()

const char * sg_route_rawpattern ( struct sg_route * route )

Returns the raw route pattern. For example, given a pattern /foo, the raw pattern is ^/foo$.

Parameters

[in] route Route handle.

Returns: Raw pattern as a null-terminated string.

Return values

NULL	If `route` is null and set the `errno` to `EINVAL`.

◆ sg_route_pattern()

char * sg_route_pattern ( struct sg_route * route )

Returns the route pattern.

Parameters

[in] route Route handle.

Returns: Pattern as a null-terminated string.

Return values

NULL	If `route` is null and set the `errno` to `EINVAL`. If no memory space is available and set the `errno` to `ENOMEM`.

Warning: The caller must free the returned value.

◆ sg_route_path()

const char * sg_route_path ( struct sg_route * route )

Returns the route path.

Parameters

[in] route Route handle.

Returns: Path component as a null-terminated string.

Return values

NULL	If `route` is null and set the `errno` to `EINVAL`.

Examples: example_entrypoint.c, example_router_segments.c, example_router_simple.c, and example_router_vars.c.

◆ sg_route_segments_iter()

int sg_route_segments_iter	(	struct sg_route *	route,
		sg_segments_iter_cb	cb,
		void *	cls
	)

Iterates over path segments.

Parameters

[in]	route	Route handle.
[in]	cb	Callback to iterate the path segments.
[in,out]	cls	User-specified value.

Return values

0	Success.
EINVAL	Invalid argument.

Returns: Callback result when it is different from 0.

Examples: example_router_segments.c.

◆ sg_route_vars_iter()

int sg_route_vars_iter	(	struct sg_route *	route,
		sg_vars_iter_cb	cb,
		void *	cls
	)

Iterates over path variables.

Parameters

[in]	route	Route handle.
[in]	cb	Callback to iterate the path variables.
[in,out]	cls	User-specified value.

Return values

0	Success.
EINVAL	Invalid argument.
ENOMEM	Out of memory.

Returns: Callback result when it is different from 0.

Examples: example_router_srv.c, and example_router_vars.c.

◆ sg_route_user_data()

void * sg_route_user_data ( struct sg_route * route )

Gets user data from the route handle.

Parameters

[in] route Route handle.

Returns: User data pointer.

Return values

NULL	If `route` is null and set the `errno` to `EINVAL`.

Examples: example_router_srv.c.

◆ sg_routes_add2()

int sg_routes_add2	(	struct sg_route **	routes,
		struct sg_route **	route,
		const char *	pattern,
		char *	errmsg,
		size_t	errlen,
		sg_route_cb	cb,
		void *	cls
	)

Adds a route item to the route list routes.

Parameters

[in,out]	routes	Route list pointer to add a new route item.
[in,out]	route	Pointer of the variable to store the added route reference.
[in]	pattern	Pattern as a null-terminated string. It must be a valid regular expression in PCRE2 syntax.
[in,out]	errmsg	Pointer of a string to store the error message.
[in]	errlen	Length of the error message.
[in]	cb	Callback to handle the path routing.
[in]	cls	User-defined closure.

Return values

0	Success.
EINVAL	Invalid argument.
EALREADY	Route already added.
ENOMEM	Out of memory.

Note: The pattern is enclosed between ^ and $ automatically if it does not start with (.; The escape sequence \K is not supported. It causes EINVAL if used.; The pattern is compiled using just-in-time optimization (JIT) when it is supported.

◆ sg_routes_add()

bool sg_routes_add	(	struct sg_route **	routes,
		const char *	pattern,
		sg_route_cb	cb,
		void *	cls
	)

Adds a route item to the route list routes. It uses the stderr to print the validation errors.

Parameters

[in,out]	routes	Route list pointer to add a new route item.
[in]	pattern	Pattern as a null-terminated string. It must be a valid regular expression in PCRE2 syntax.
[in]	cb	Callback to handle the path routing.
[in]	cls	User-defined closure.

Return values

0	Success.
EINVAL	Invalid argument.
EALREADY	Route already added.
ENOMEM	Out of memory.

Note: The pattern is enclosed between ^ and $ automatically if it does not start with (.; The escape sequence \K is not supported. It causes EINVAL if used.; The pattern is compiled using just-in-time optimization (JIT) when it is supported.

Examples: example_entrypoint.c, example_router_segments.c, example_router_simple.c, example_router_srv.c, and example_router_vars.c.

◆ sg_routes_rm()

int sg_routes_rm	(	struct sg_route **	routes,
		const char *	pattern
	)

Removes a route item from the route list routes.

Parameters

[in,out]	routes	Route list pointer to add a new route item.
[in]	pattern	Pattern as a null-terminated string of the route to be removed.

Return values

0	Success.
EINVAL	Invalid argument.
ENOENT	Route already removed.

◆ sg_routes_iter()

int sg_routes_iter	(	struct sg_route *	routes,
		sg_routes_iter_cb	cb,
		void *	cls
	)

Iterates over all the routes in the route list routes.

Parameters

[in]	routes	Route list handle.
[in]	cb	Callback to iterate over route items.
[in]	cls	User-defined closure.

Return values

0	Success.
EINVAL	Invalid argument.
E<ERROR>	User-defined error to abort the list iteration.

◆ sg_routes_next()

int sg_routes_next ( struct sg_route ** route )

Returns the next route into the route list.

Parameters

[in,out] route Pointer to the next route item.

Return values

0	Success.
EINVAL	Invalid argument.

◆ sg_routes_count()

unsigned int sg_routes_count ( struct sg_route * routes )

Counts the total routes in the route list routes.

Parameters

[in] routes Route list handle.

Returns: Total of route items.

Return values

0	If the list is empty or null.

◆ sg_routes_cleanup()

int sg_routes_cleanup ( struct sg_route ** routes )

Cleans the entire route list.

Parameters

[in,out] routes Pointer to the route list.

Examples: example_entrypoint.c, example_router_segments.c, example_router_simple.c, example_router_srv.c, and example_router_vars.c.

◆ sg_router_new()

struct sg_router * sg_router_new ( struct sg_route * routes )

Creates a new path router handle. It requires a filled route list routes.

Parameters

[in] routes Route list handle.

Returns: New router handle.

Return values

NULL	If the `routes` is null and set the `errno` to `EINVAL` or no memory space.

Examples: example_entrypoint.c, example_router_segments.c, example_router_simple.c, example_router_srv.c, and example_router_vars.c.

◆ sg_router_free()

void sg_router_free ( struct sg_router * router )

Frees the router handle previously allocated by sg_router_new().

Parameters

[in] router Router handle.

Examples: example_entrypoint.c, example_router_segments.c, example_router_simple.c, example_router_srv.c, and example_router_vars.c.

◆ sg_router_dispatch2()

int sg_router_dispatch2	(	struct sg_router *	router,
		const char *	path,
		void *	user_data,
		sg_router_dispatch_cb	dispatch_cb,
		void *	cls,
		sg_router_match_cb	match_cb
	)

Dispatches a route that its pattern matches the path passed in path.

Parameters

[in]	router	Router handle.
[in]	path	Path to dispatch a route.
[in]	user_data	User data pointer to be held by the route.
[in]	dispatch_cb	Callback triggered for each route item in the route dispatching loop.
[in]	cls	User-defined closure passed to the `dispatch_cb` and `match_cb` callbacks.
[in]	match_cb	Callback triggered when the path matches the route pattern.

Return values

0	Success.
EINVAL	Invalid argument.
ENOENT	Route not found or path not matched.
E<ERROR>	User-defined error in `dispatch_cb` or `match_cb`.

Note: The route callback sg_route_cb is triggered when the path matches the route pattern.; The match logic uses just-in-time optimization (JIT) when it is supported.

◆ sg_router_dispatch()

int sg_router_dispatch	(	struct sg_router *	router,
		const char *	path,
		void *	user_data
	)

Dispatches a route that its pattern matches the path passed in path.

Parameters

[in]	router	Router handle.
[in]	path	Path to dispatch a route.
[in]	user_data	User data pointer to be held by the route.

Return values

0	Success.
EINVAL	Invalid argument.
ENOENT	Route not found or path not matched.
E<ERROR>	User-defined error in `dispatch_cb` or `match_cb`.

Note: The route callback sg_route_cb is triggered when the path matches the route pattern.; The match logic uses just-in-time optimization (JIT) when it is supported.

Examples: example_entrypoint.c, example_router_segments.c, example_router_simple.c, example_router_srv.c, and example_router_vars.c.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ sg_entrypoints_iter_cb

◆ sg_segments_iter_cb

◆ sg_vars_iter_cb

◆ sg_route_cb

◆ sg_routes_iter_cb

◆ sg_router_dispatch_cb

◆ sg_router_match_cb

Function Documentation

◆ sg_entrypoint_name()

◆ sg_entrypoint_set_user_data()

◆ sg_entrypoint_user_data()

◆ sg_entrypoints_new()

◆ sg_entrypoints_free()

◆ sg_entrypoints_add()

◆ sg_entrypoints_rm()

◆ sg_entrypoints_iter()

◆ sg_entrypoints_clear()

◆ sg_entrypoints_find()

◆ sg_route_handle()

◆ sg_route_match()

◆ sg_route_rawpattern()

◆ sg_route_pattern()

◆ sg_route_path()

◆ sg_route_segments_iter()

◆ sg_route_vars_iter()

◆ sg_route_user_data()

◆ sg_routes_add2()

◆ sg_routes_add()

◆ sg_routes_rm()

◆ sg_routes_iter()

◆ sg_routes_next()

◆ sg_routes_count()

◆ sg_routes_cleanup()

◆ sg_router_new()

◆ sg_router_free()

◆ sg_router_dispatch2()

◆ sg_router_dispatch()