The environment-driven daemon option matrix shared by the tests. More...

#include <stddef.h>
#include <microhttpd.h>

Include dependency graph for mhd_opt_matrix.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	MHD_OptMatrixProfile

Macros
#define	MHD_OPT_MATRIX_PROFILE_ENV "MHD_TEST_PROFILE"

#define	MHD_OPT_MATRIX_MEM_ENV "MHD_TEST_MEM_LIMIT"

#define	MHD_OPT_MATRIX_DISCP_ENV "MHD_TEST_DISCIPLINE"

#define	MHD_OPT_MATRIX_STRICT_ENV "MHD_TEST_STRICT_FOR_CLIENT"

#define	MHD_OPT_MATRIX_THREADING_ENV "MHD_TEST_THREADING"

#define	MHD_OPT_MATRIX_POLL_ENV "MHD_TEST_POLL"

Enumerations
enum	MHD_OptMatrixThreading { MHD_OPT_MATRIX_THR_EXTERNAL = 0 , MHD_OPT_MATRIX_THR_INTERNAL = 1 , MHD_OPT_MATRIX_THR_PER_CONNECTION = 2 , MHD_OPT_MATRIX_THR_POOL = 3 }

enum	MHD_OptMatrixPoll { MHD_OPT_MATRIX_POLL_SELECT = 0 , MHD_OPT_MATRIX_POLL_POLL = 1 , MHD_OPT_MATRIX_POLL_EPOLL = 2 }

Functions
unsigned int	mhd_opt_matrix_num_profiles (void)

const struct MHD_OptMatrixProfile *	mhd_opt_matrix_profile (unsigned int idx)

const struct MHD_OptMatrixProfile *	mhd_opt_matrix_lookup (const char *name_or_idx)

const struct MHD_OptMatrixProfile *	mhd_opt_matrix_from_env (void)

int	mhd_opt_matrix_effective_discipline (const struct MHD_OptMatrixProfile *prof)

int	mhd_opt_matrix_profile_supported (const struct MHD_OptMatrixProfile *prof)

const char *	mhd_opt_matrix_describe (const struct MHD_OptMatrixProfile prof, char buf, size_t buf_size)

unsigned int	mhd_opt_matrix_fill_options (const struct MHD_OptMatrixProfile prof, struct MHD_OptionItem ops, unsigned int max_ops)

unsigned int	mhd_opt_matrix_daemon_flags (const struct MHD_OptMatrixProfile *prof, unsigned int base_flags, int allow_external)

int	mhd_opt_matrix_is_external (const struct MHD_OptMatrixProfile *prof)

int	mhd_opt_matrix_raise_mem_limit (struct MHD_OptMatrixProfile *prof, size_t min_limit)

void	mhd_opt_matrix_print_notice (const char *test_name)

Detailed Description

The environment-driven daemon option matrix shared by the tests.

Author: Christian Grothoff

This header must be included after "platform.h" and <microhttpd.h>.

What this is

Almost every test in this directory starts its daemon with one hard-coded set of options, so the whole test suite only ever exercises a single point of a large configuration space. This helper turns that space into a small table of named profiles and lets the profile be selected from the environment, so that an already built test binary can be re-run across the whole matrix without recompiling anything (see contrib/run-option-matrix.sh).

The dimensions of the matrix are:

MHD_OPTION_CONNECTION_MEMORY_LIMIT in {64, 128, 256, 512, 1024, 2048, 3072, 4096, library default}. 64 is the smallest value MHD accepts (anything below is rounded up to 64, see daemon.c). Everything up to 2048 keeps the read buffer below MHD_BUF_INC_SIZE (1500) resp. small enough to unlock the read-buffer "shift back" path fixed by commit 29eaa56b, 3072 and 4096 do not, so both sides of that boundary are in the sweep;
MHD_OPTION_CLIENT_DISCIPLINE_LVL in {-3 ... 3};
MHD_OPTION_STRICT_FOR_CLIENT, the older two-valued form of the same knob, so that its translation code is covered as well. Beware: that option maps every value of -1 or below to client discipline level -3, the most permissive one (daemon.c:7102-7106), so an application asking for "slightly lenient" in fact selects the most lenient mode;
the threading mode: external polling, internal polling thread, thread-per-connection and thread pool;
the polling backend: select(), poll() and epoll. Profiles asking for a backend that this build does not provide are reported as unsupported by mhd_opt_matrix_profile_supported().

MHD_OPTION_SERVER_INSANITY is deliberately not a dimension: in this MHD version enum MHD_DisableSanityCheck has exactly one member, MHD_DSC_SANE (zero), so the option cannot disable anything.

Environment variables

MHD_OPT_MATRIX_PROFILE_ENV ("MHD_TEST_PROFILE") - the profile to use, given either by name ("mem-512") or by index ("4"). The special value "list" is not handled here; contrib/run-option-matrix.sh knows the names.
MHD_OPT_MATRIX_MEM_ENV ("MHD_TEST_MEM_LIMIT") - override the connection memory limit of the selected profile. "0" or "default" selects the library default.
MHD_OPT_MATRIX_DISCP_ENV ("MHD_TEST_DISCIPLINE") - override the client discipline level (-3 ... 3) and use MHD_OPTION_CLIENT_DISCIPLINE_LVL.
MHD_OPT_MATRIX_STRICT_ENV ("MHD_TEST_STRICT_FOR_CLIENT") - override the same knob but use the deprecated MHD_OPTION_STRICT_FOR_CLIENT instead.
MHD_OPT_MATRIX_THREADING_ENV ("MHD_TEST_THREADING") - one of "external", "internal", "per-connection", "pool".
MHD_OPT_MATRIX_POLL_ENV ("MHD_TEST_POLL") - one of "select", "poll", "epoll".

If none of these variables is set, mhd_opt_matrix_from_env() returns NULL and every test keeps its previous, hard-coded behaviour. This is what a stock "make check" does, so nothing regresses.

Definition in file mhd_opt_matrix.h.

Macro Definition Documentation

◆ MHD_OPT_MATRIX_DISCP_ENV

#define MHD_OPT_MATRIX_DISCP_ENV "MHD_TEST_DISCIPLINE"

The name of the environment variable overriding the discipline level.

Definition at line 102 of file mhd_opt_matrix.h.

Referenced by mhd_opt_matrix_from_env().

◆ MHD_OPT_MATRIX_MEM_ENV

#define MHD_OPT_MATRIX_MEM_ENV "MHD_TEST_MEM_LIMIT"

The name of the environment variable overriding the memory limit.

Definition at line 97 of file mhd_opt_matrix.h.

Referenced by mhd_opt_matrix_from_env().

◆ MHD_OPT_MATRIX_POLL_ENV

#define MHD_OPT_MATRIX_POLL_ENV "MHD_TEST_POLL"

The name of the environment variable overriding the polling backend.

Definition at line 118 of file mhd_opt_matrix.h.

Referenced by mhd_opt_matrix_from_env().

◆ MHD_OPT_MATRIX_PROFILE_ENV

#define MHD_OPT_MATRIX_PROFILE_ENV "MHD_TEST_PROFILE"

The name of the environment variable selecting the profile.

Definition at line 92 of file mhd_opt_matrix.h.

Referenced by mhd_opt_matrix_from_env().

◆ MHD_OPT_MATRIX_STRICT_ENV

#define MHD_OPT_MATRIX_STRICT_ENV "MHD_TEST_STRICT_FOR_CLIENT"

The name of the environment variable overriding the discipline level via the deprecated MHD_OPTION_STRICT_FOR_CLIENT option.

Definition at line 108 of file mhd_opt_matrix.h.

Referenced by mhd_opt_matrix_from_env().

◆ MHD_OPT_MATRIX_THREADING_ENV

#define MHD_OPT_MATRIX_THREADING_ENV "MHD_TEST_THREADING"

The name of the environment variable overriding the threading mode.

Definition at line 113 of file mhd_opt_matrix.h.

Referenced by mhd_opt_matrix_from_env().

Enumeration Type Documentation

◆ MHD_OptMatrixPoll

enum MHD_OptMatrixPoll

The polling backend of a profile.

Enumerator
MHD_OPT_MATRIX_POLL_SELECT	Use select().
MHD_OPT_MATRIX_POLL_POLL	Use poll(), needs MHD_FEATURE_POLL.
MHD_OPT_MATRIX_POLL_EPOLL	Use epoll, needs MHD_FEATURE_EPOLL.

Definition at line 150 of file mhd_opt_matrix.h.

◆ MHD_OptMatrixThreading

enum MHD_OptMatrixThreading

The threading mode of a profile.

Enumerator
MHD_OPT_MATRIX_THR_EXTERNAL	External polling: the application drives the daemon with MHD_run().
MHD_OPT_MATRIX_THR_INTERNAL	One internal polling thread for all connections.
MHD_OPT_MATRIX_THR_PER_CONNECTION	One internal thread per connection.
MHD_OPT_MATRIX_THR_POOL	A pool of internal polling threads.

Definition at line 123 of file mhd_opt_matrix.h.

Function Documentation

◆ mhd_opt_matrix_daemon_flags()

unsigned int mhd_opt_matrix_daemon_flags	(	const struct MHD_OptMatrixProfile *	prof,
		unsigned int	base_flags,
		int	allow_external )

Combine the daemon flags required by prof with base_flags.

Parameters

prof	the profile to apply, may be NULL (base_flags is returned)
base_flags	the flags the caller wants in any case, e.g. MHD_USE_ERROR_LOG
allow_external	if zero, a profile that asks for external polling is served with an internal polling thread instead; use this in tests whose client cannot call MHD_run()

Returns: the flags for MHD_start_daemon()

Definition at line 458 of file mhd_opt_matrix.c.

References MHD_OPT_MATRIX_POLL_EPOLL, MHD_OPT_MATRIX_POLL_POLL, MHD_OPT_MATRIX_POLL_SELECT, MHD_OPT_MATRIX_THR_EXTERNAL, MHD_OPT_MATRIX_THR_INTERNAL, MHD_OPT_MATRIX_THR_PER_CONNECTION, MHD_OPT_MATRIX_THR_POOL, MHD_USE_EPOLL, MHD_USE_INTERNAL_POLLING_THREAD, MHD_USE_POLL, MHD_USE_THREAD_PER_CONNECTION, NULL, MHD_OptMatrixProfile::poll_backend, and MHD_OptMatrixProfile::threading.

◆ mhd_opt_matrix_describe()

const char * mhd_opt_matrix_describe	(	const struct MHD_OptMatrixProfile *	prof,
		char *	buf,
		size_t	buf_size )

Render a one-line, human readable description of prof.

Parameters

	prof	the profile to describe
[out]	buf	the buffer to write to
	buf_size	the size of buf

Returns: buf

Definition at line 367 of file mhd_opt_matrix.c.

References MHD_OptMatrixProfile::discipline_lvl, MHD_OptMatrixProfile::mem_limit, mhd_opt_matrix_effective_discipline(), MHD_OPT_MATRIX_THR_POOL, MHD_OptMatrixProfile::name, NULL, MHD_OptMatrixProfile::poll_backend, MHD_OptMatrixProfile::thread_pool_size, MHD_OptMatrixProfile::threading, and MHD_OptMatrixProfile::use_legacy_strict.

Referenced by mhd_opt_matrix_print_notice().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mhd_opt_matrix_effective_discipline()

int mhd_opt_matrix_effective_discipline ( const struct MHD_OptMatrixProfile * prof )

Get the client discipline level that MHD will really use for prof.

This is not always prof->discipline_lvl: MHD_OPTION_STRICT_FOR_CLIENT only has two settings, and daemon.c:7102-7106 maps every value of -1 or below to level -3 (the most permissive one) and every value of 1 or above to level 1. A caller that decides what a request must do therefore has to ask for the effective level, not for the configured one - a test that believes it asked for "slightly lenient" in fact runs at -3.

Parameters

prof	the profile to inspect, may be NULL (0 is returned then)

Returns: the client discipline level in effect

Definition at line 323 of file mhd_opt_matrix.c.

References MHD_OptMatrixProfile::discipline_lvl, NULL, and MHD_OptMatrixProfile::use_legacy_strict.

Referenced by mhd_opt_matrix_describe().

Here is the caller graph for this function:

◆ mhd_opt_matrix_fill_options()

unsigned int mhd_opt_matrix_fill_options	(	const struct MHD_OptMatrixProfile *	prof,
		struct MHD_OptionItem *	ops,
		unsigned int	max_ops )

Fill ops with the options of prof.

The array is terminated with an MHD_OPTION_END element, so it can be passed to MHD_start_daemon() as

MHD_start_daemon (flags, port, NULL, NULL, ahc, cls,
                  MHD_OPTION_ARRAY, ops,
                  ... other options ...,
                  MHD_OPTION_END);

which works for a varargs call just as well as for a call that already uses MHD_OPTION_ARRAY.

Parameters

	prof	the profile to apply, may be NULL (only MHD_OPTION_END is stored then)
[out]	ops	the array to fill
	max_ops	the number of elements of ops, at least 4

Returns: the number of elements used, including the terminating MHD_OPTION_END; zero if ops is too small

Definition at line 414 of file mhd_opt_matrix.c.

References MHD_OptMatrixProfile::discipline_lvl, MHD_OptMatrixProfile::mem_limit, MHD_OPT_MATRIX_THR_POOL, MHD_OPTION_CLIENT_DISCIPLINE_LVL, MHD_OPTION_CONNECTION_MEMORY_LIMIT, MHD_OPTION_END, MHD_OPTION_STRICT_FOR_CLIENT, MHD_OPTION_THREAD_POOL_SIZE, NULL, MHD_OptionItem::option, MHD_OptionItem::ptr_value, MHD_OptMatrixProfile::thread_pool_size, MHD_OptMatrixProfile::threading, MHD_OptMatrixProfile::use_legacy_strict, and MHD_OptionItem::value.

◆ mhd_opt_matrix_from_env()

const struct MHD_OptMatrixProfile * mhd_opt_matrix_from_env ( void )

Get the profile selected by the environment.

Returns: NULL if the environment selects nothing, in which case the caller must keep its own, previous configuration; otherwise a pointer to a static profile that stays valid until the next call

Definition at line 227 of file mhd_opt_matrix.c.

References MHD_OptMatrixProfile::discipline_lvl, env_error(), env_parsed, env_profile, env_profile_name, env_selected, MHD_OptMatrixProfile::mem_limit, MHD_OPT_MATRIX_DISCP_ENV, mhd_opt_matrix_lookup(), MHD_OPT_MATRIX_MEM_ENV, MHD_OPT_MATRIX_POLL_ENV, MHD_OPT_MATRIX_PROFILE_ENV, MHD_OPT_MATRIX_STRICT_ENV, MHD_OPT_MATRIX_THR_POOL, MHD_OPT_MATRIX_THREADING_ENV, MHD_OptMatrixProfile::name, NULL, opt_profiles, parse_poll(), parse_threading(), MHD_OptMatrixProfile::poll_backend, MHD_OptMatrixProfile::thread_pool_size, MHD_OptMatrixProfile::threading, and MHD_OptMatrixProfile::use_legacy_strict.

Referenced by mhd_opt_matrix_print_notice().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mhd_opt_matrix_is_external()

int mhd_opt_matrix_is_external ( const struct MHD_OptMatrixProfile * prof )

Check whether prof needs the application to drive MHD_run().

Parameters

prof	the profile to check, may be NULL

Returns: non-zero if the daemon has no internal thread

Definition at line 499 of file mhd_opt_matrix.c.

References MHD_OPT_MATRIX_THR_EXTERNAL, NULL, and MHD_OptMatrixProfile::threading.

◆ mhd_opt_matrix_lookup()

const struct MHD_OptMatrixProfile * mhd_opt_matrix_lookup ( const char * name_or_idx )

Look up a profile by name or by decimal index.

Parameters

name_or_idx the name ("mem-512") or the index ("4")

Returns: the profile, or NULL if name_or_idx matches nothing

Definition at line 136 of file mhd_opt_matrix.c.

References MHD_OptMatrixProfile::name, NULL, NUM_PROFILES, and opt_profiles.

Referenced by mhd_opt_matrix_from_env().

Here is the caller graph for this function:

◆ mhd_opt_matrix_num_profiles()

unsigned int mhd_opt_matrix_num_profiles ( void )

The number of built-in profiles.

Definition at line 122 of file mhd_opt_matrix.c.

References NUM_PROFILES.

◆ mhd_opt_matrix_print_notice()

void mhd_opt_matrix_print_notice ( const char * test_name )

Print the one-line notice naming the profile in use and, if a profile is selected, the profile.

Parameters

test_name the name of the calling test, used as the line prefix

Definition at line 521 of file mhd_opt_matrix.c.

References mhd_opt_matrix_describe(), mhd_opt_matrix_from_env(), MHD_OptMatrixProfile::name, and NULL.

Here is the call graph for this function:

◆ mhd_opt_matrix_profile()

const struct MHD_OptMatrixProfile * mhd_opt_matrix_profile ( unsigned int idx )

Get the built-in profile number idx.

Profile zero is the "default" profile: the library defaults for every dimension plus one internal polling thread, i.e. the configuration the tests of this directory used before the matrix was introduced.

Parameters

idx	the index of the profile, wraps around

Returns: the profile, never NULL

Definition at line 129 of file mhd_opt_matrix.c.

References NUM_PROFILES, and opt_profiles.

◆ mhd_opt_matrix_profile_supported()

int mhd_opt_matrix_profile_supported ( const struct MHD_OptMatrixProfile * prof )

Check whether prof can be used by this build at run time.

Parameters

prof	the profile to check

Returns: non-zero if the profile is usable, zero if the required threading support or polling backend is missing

Definition at line 339 of file mhd_opt_matrix.c.

References MHD_FEATURE_EPOLL, MHD_FEATURE_POLL, MHD_FEATURE_THREADS, MHD_is_feature_supported(), MHD_OPT_MATRIX_POLL_EPOLL, MHD_OPT_MATRIX_POLL_POLL, MHD_OPT_MATRIX_POLL_SELECT, MHD_OPT_MATRIX_THR_EXTERNAL, MHD_OPT_MATRIX_THR_PER_CONNECTION, MHD_YES, NULL, MHD_OptMatrixProfile::poll_backend, and MHD_OptMatrixProfile::threading.

Here is the call graph for this function:

◆ mhd_opt_matrix_raise_mem_limit()

int mhd_opt_matrix_raise_mem_limit	(	struct MHD_OptMatrixProfile *	prof,
		size_t	min_limit )

Raise the connection memory limit of prof to at least min_limit.

Tests that cannot work with a tiny connection pool (because the requests they must send do not fit into it) use this to keep the other dimensions of the matrix while staying functional. The change must be reported in the test output so that the log stays truthful.

Parameters

[in,out]	prof	the profile to adjust, must be a caller-owned copy
	min_limit	the smallest acceptable limit, zero does nothing

Returns: non-zero if the limit was actually raised

Definition at line 508 of file mhd_opt_matrix.c.

References MHD_OptMatrixProfile::mem_limit, and NULL.

Data Structures

Macros

Enumerations

Functions

Detailed Description

What this is

Environment variables

Macro Definition Documentation

◆ MHD_OPT_MATRIX_DISCP_ENV

◆ MHD_OPT_MATRIX_MEM_ENV

◆ MHD_OPT_MATRIX_POLL_ENV

◆ MHD_OPT_MATRIX_PROFILE_ENV

◆ MHD_OPT_MATRIX_STRICT_ENV

◆ MHD_OPT_MATRIX_THREADING_ENV

Enumeration Type Documentation

◆ MHD_OptMatrixPoll

◆ MHD_OptMatrixThreading

Function Documentation

◆ mhd_opt_matrix_daemon_flags()

◆ mhd_opt_matrix_describe()

◆ mhd_opt_matrix_effective_discipline()

◆ mhd_opt_matrix_fill_options()

◆ mhd_opt_matrix_from_env()

◆ mhd_opt_matrix_is_external()

◆ mhd_opt_matrix_lookup()

◆ mhd_opt_matrix_num_profiles()

◆ mhd_opt_matrix_print_notice()

◆ mhd_opt_matrix_profile()

◆ mhd_opt_matrix_profile_supported()

◆ mhd_opt_matrix_raise_mem_limit()