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

Previous topic

1. Interface conventions

Next topic

3. Error handing

Downloads

All MPS Kit releases

Issues

All open issues

Contact us

mps-questions@ravenbrook.com
#memorypoolsystem on irc.freenode.net