2. Keyword arguments

Some functions in the MPS interface take keyword arguments in order to pass values that might be optional, or are only required in some circumstances. For example, the function mps_arena_create_k() creates any class of arena, but client arenas require you to specify a base address. These arguments are passed in a keyword argument array, like this:

mps_res_t res;
mps_arena_t arena;
mps_arg_s args[3];
args[0].key = MPS_KEY_ARENA_SIZE;
args[0].val.size = 6553600;
args[1].key = MPS_KEY_ARENA_CL_BASE;
args[1].val.addr = base_address;
args[2].key = MPS_KEY_ARGS_END;
res = mps_arena_create_k(&arena, mps_arena_class_cl(), args);

Each keyword argument in the array is a structure of type mps_arg_s.

For convenience and robustness, the MPS interface includes macros to help with forming keyword argument lists:

MPS_ARGS_BEGIN(args) {
    MPS_ARGS_ADD(args, MPS_KEY_ARENA_SIZE, 6553600);
    MPS_ARGS_ADD(args, MPS_KEY_ARENA_CL_BASE, base_address);
    res = mps_arena_create_k(&arena, mps_arena_class_cl(), args);
} MPS_ARGS_END(args);

The argument array must not be NULL, and must end with MPS_KEY_ARGS_END. If you don’t want to pass any arguments, you can pass mps_args_none.

When a function that takes keyword arguments returns, the keyword argument array has been modified to remove any arguments that have been used. If all arguments have been used, the first element key is now MPS_KEY_ARGS_END.

mps_arg_s

The type of the structure used to represent a single keyword argument to a function.

typedef struct mps_arg_s {
    mps_key_t key;
    union { /* many fields; see table below */ } val;
} mps_arg_s;

key identifies the key. It must be one of the values listed in the documentation for the type mps_key_t.

val is the corresponding value. This union contains many fields: one for each keyword argument type. The table given in the documentation for mps_key_t below indicates which structure field is used by each keyword.

Note

If you use the convenience macro MPS_ARGS_ADD() then you don’t need to know the name of the field.

mps_args_none

An array of mps_arg_s representing the empty list of keyword arguments. Equivalent to:

mps_arg_s mps_args_none[] = {{MPS_KEY_ARGS_END}};

mps_key_t

The type of keyword argument keys. Must take one of the following values:

Keyword	Type & field in arg.val	See
MPS_KEY_ARGS_END	none	see above
MPS_KEY_ALIGN	mps_align_t align	mps_class_mv(), mps_class_mvff(), mps_class_mvt()
MPS_KEY_AMS_SUPPORT_AMBIGUOUS	mps_bool_t b	mps_class_ams()
MPS_KEY_ARENA_CL_BASE	mps_addr_t addr	mps_arena_class_cl()
MPS_KEY_ARENA_SIZE	size_t size	mps_arena_class_vm(), mps_arena_class_cl()
MPS_KEY_ARENA_GRAIN_SIZE	size_t size	mps_arena_class_vm(), mps_arena_class_cl()
MPS_KEY_AWL_FIND_DEPENDENT	void *(*)(void *) addr_method	mps_class_awl()
MPS_KEY_CHAIN	mps_chain_t chain	mps_class_amc(), mps_class_amcz(), mps_class_ams(), mps_class_awl(), mps_class_lo()
MPS_KEY_EXTEND_BY	size_t size	mps_class_amc(), mps_class_amcz(), mps_class_mfs(), mps_class_mv(), mps_class_mvff()
MPS_KEY_FMT_ALIGN	mps_align_t align	mps_fmt_create_k()
MPS_KEY_FMT_CLASS	mps_fmt_class_t fmt_class	mps_fmt_create_k()
MPS_KEY_FMT_FWD	mps_fmt_fwd_t fmt_fwd	mps_fmt_create_k()
MPS_KEY_FMT_HEADER_SIZE	size_t size	mps_fmt_create_k()
MPS_KEY_FMT_ISFWD	mps_fmt_isfwd_t fmt_isfwd	mps_fmt_create_k()
MPS_KEY_FMT_PAD	mps_fmt_pad_t fmt_pad	mps_fmt_create_k()
MPS_KEY_FMT_SCAN	mps_fmt_scan_t fmt_scan	mps_fmt_create_k()
MPS_KEY_FMT_SKIP	mps_fmt_skip_t fmt_skip	mps_fmt_create_k()
MPS_KEY_FORMAT	mps_fmt_t format	mps_class_amc(), mps_class_amcz(), mps_class_ams(), mps_class_awl(), mps_class_lo() , mps_class_snc()
MPS_KEY_GEN	unsigned u	mps_class_ams(), mps_class_awl(), mps_class_lo()
MPS_KEY_INTERIOR	mps_bool_t b	mps_class_amc(), mps_class_amcz()
MPS_KEY_MAX_SIZE	size_t size	mps_class_mv()
MPS_KEY_MEAN_SIZE	size_t size	mps_class_mv(), mps_class_mvt(), mps_class_mvff()
MPS_KEY_MFS_UNIT_SIZE	size_t size	mps_class_mfs()
MPS_KEY_MIN_SIZE	size_t size	mps_class_mvt()
MPS_KEY_MVFF_ARENA_HIGH	mps_bool_t b	mps_class_mvff()
MPS_KEY_MVFF_FIRST_FIT	mps_bool_t b	mps_class_mvff()
MPS_KEY_MVFF_SLOT_HIGH	mps_bool_t b	mps_class_mvff()
MPS_KEY_MVT_FRAG_LIMIT	mps_count_t count	mps_class_mvt()
MPS_KEY_MVT_RESERVE_DEPTH	mps_count_t count	mps_class_mvt()
MPS_KEY_POOL_DEBUG_OPTIONS	mps_pool_debug_options_s* pool_debug_options	mps_class_ams_debug(), mps_class_mv_debug(), mps_class_mvff_debug()
MPS_KEY_RANK	mps_rank_t rank	mps_class_ams(), mps_class_awl(), mps_class_snc()
MPS_KEY_SPARE	double d	mps_class_mvff()
MPS_KEY_VMW3_TOP_DOWN	mps_bool_t b	mps_arena_class_vm()

MPS_ARGS_BEGIN(args)

Start construction of a list of keyword arguments. This macro must be used like this:

MPS_ARGS_BEGIN(args) {
    MPS_ARGS_ADD(args, MPS_KEY_ARENA_SIZE, 6553600);
    MPS_ARGS_ADD(args, MPS_KEY_ARENA_CL_BASE, base_address);
    res = mps_arena_create_k(&arena, mps_arena_class_cl(), args);
} MPS_ARGS_END(args);

That is, you must call MPS_ARGS_ADD() (or MPS_ARGS_ADD_FIELD()) zero or more times, and then pass the arguments to a function.

args is the name of the array that contains the keyword arguments. The array is stack-allocated, and exists between MPS_ARGS_BEGIN and MPS_ARGS_END.

It is safe to nest blocks created by MPS_ARGS_BEGIN and MPS_ARGS_END.

MPS_ARGS_ADD(mps_arg_s args[], mps_key_t key, value)

Add an argument to a list of keyword arguments. This macro must be used only between MPS_ARGS_BEGIN and MPS_ARGS_END.

args is the name of array that contains the keyword arguments. It must match the argument to the preceding call to MPS_ARGS_BEGIN().

key is the keyword identifying this argument. It must be one of the key names starting with MPS_KEY_ that are listed in the table in the documentation for mps_key_t.

value is the value for this argument.

MPS_ARGS_ADD_FIELD(mps_arg_s args[], mps_key_t key, field, value)

Add an argument to a list of keyword arguments. This macro must be used only between MPS_ARGS_BEGIN and MPS_ARGS_END.

args is the name of array that contains the keyword arguments. It must match the argument to the preceding call to MPS_ARGS_BEGIN().

key is the keyword identifying this argument.

field is the name of the field in the val union in the structure mps_args_s.

value is the value for this argument.

Note

You should prefer to use MPS_ARGS_ADD(), because then you don’t need to look up the name of the field.

MPS_ARGS_END(args)

Finish using a list of keyword arguments whose construction was started by MPS_ARGS_BEGIN().

args is the name of array that contains the keyword arguments. It must match the argument to the preceding call to MPS_ARGS_BEGIN().

MPS_ARGS_DONE(args)

Deprecated

starting with version 1.113.

Formerly this was used to finalize a list of keyword arguments before passing it to a function. It is no longer needed.