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_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_GRAIN_SIZE

size_t size

mps_arena_class_vm(), mps_arena_class_cl()

MPS_KEY_ARENA_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_COMMIT_LIMIT

size_t size

mps_arena_class_vm(), mps_arena_class_cl()

MPS_KEY_EXTEND_BY

size_t size

mps_class_amc(), mps_class_amcz(), mps_class_mfs(), 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_MEAN_SIZE

size_t size

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_word_t count

mps_class_mvt()

MPS_KEY_MVT_RESERVE_DEPTH

mps_word_t count

mps_class_mvt()

MPS_KEY_PAUSE_TIME

double d

mps_arena_class_vm(), mps_arena_class_cl()

MPS_KEY_POOL_DEBUG_OPTIONS

mps_pool_debug_option_s *pool_debug_options

mps_class_ams_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_arena_class_vm(), mps_class_mvff()

MPS_KEY_SPARE_COMMIT_LIMIT

size_t size

mps_arena_class_vm()

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