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);
    MPS_ARGS_DONE(args);
    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 either call the equivalent function that does not take keyword arguments (named without the _k) or 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 {
        mps_bool_t b;
        char c;
        const char *string;
        int i;
        unsigned u;
        long l;
        unsigned long ul;
        size_t size;
        mps_addr_t addr;
        mps_fmt_t format;
        mps_chain_t chain;
        struct mps_pool_debug_option_s *pool_debug_options;
        mps_addr_t (*addr_method)(mps_addr_t);
        mps_align_t align;
        mps_word_t count;
        void *p;
        mps_rank_t rank;
    } val;
} mps_arg_s;

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

val is the corresponding value. The table given in the documentation for mps_key_t explains which structure field is used by that keyword.

Note

If you use the convenience macros MPS_ARGS_ADD() and MPS_ARG() 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	Field	See
MPS_KEY_ARGS_END	none	see above
MPS_KEY_ALIGN	align	mps_class_mvff()
MPS_KEY_AMS_SUPPORT_AMBIGUOUS	b	mps_class_ams()
MPS_KEY_ARENA_CL_BASE	addr	mps_arena_class_cl()
MPS_KEY_ARENA_SIZE	size	mps_arena_class_vm(), mps_arena_class_cl()
MPS_KEY_AWL_FIND_DEPENDENT	addr_method	mps_class_awl()
MPS_KEY_CHAIN	chain	mps_class_amc(), mps_class_amcz(), mps_class_ams()
MPS_KEY_EXTEND_BY	size	mps_class_mfs(), mps_class_mv(), mps_class_mvff()
MPS_KEY_FORMAT	format	mps_class_amc(), mps_class_amcz(), mps_class_ams(), mps_class_awl(), mps_class_lo() , mps_class_snc()
MPS_KEY_MAX_SIZE	size	mps_class_mv()
MPS_KEY_MEAN_SIZE	size	mps_class_mv(), mps_class_mvt(), mps_class_mvff()
MPS_KEY_MFS_UNIT_SIZE	size	mps_class_mfs()
MPS_KEY_MIN_SIZE	size	mps_class_mvt()
MPS_KEY_MVFF_ARENA_HIGH	b	mps_class_mvff()
MPS_KEY_MVFF_FIRST_FIT	b	mps_class_mvff()
MPS_KEY_MVFF_SLOT_HIGH	b	mps_class_mvff()
MPS_KEY_MVT_FRAG_LIMIT	count	mps_class_mvt()
MPS_KEY_MVT_RESERVE_DEPTH	count	mps_class_mvt()
MPS_KEY_POOL_DEBUG_OPTIONS	pool_debug_options	mps_class_ams_debug(), mps_class_mv_debug(), mps_class_mvff_debug()
MPS_KEY_RANK	rank	mps_class_awl(), mps_class_snc()
MPS_KEY_VMW3_TOP_DOWN	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);
    MPS_ARGS_DONE(args);
    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 call MPS_ARGS_DONE() before passing 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_DONE(args)

Finalize 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().

After calling this macro, the array args is ready to pass to a function.

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().