56. The WriteF function

56.1. Introduction

.intro: This document describes the WriteF() function, which allows formatted output in a manner similar to ANSI C printf, but allows the MPM to operate in a freestanding environment (see design.mps.exec-env).

.background: The documents design.mps.exec-env and design.mps.lib describe the design of the library interface and the reason that it exists.

56.2. Design

.no-printf: There is no dependency on printf(). The MPM only depends on fputc() and fputs(), via the Library Interface (design.mps.lib). This makes it much easier to deploy the MPS in a freestanding environment. This is achieved by implementing our own internal output routines in mpm.c.

Our output requirements are few, so the code is short. The only output function which should be used in the rest of the MPM is WriteF(), which is similar to fprintf():

Res WriteF(mps_lib_FILE *stream, ...)

WriteF() expects a format string followed by zero or more items to insert into the output, followed by another format string, more items, and so on, and finally a NULL format string. For example:

WriteF(stream,
       "Hello: $A\n", address,
       "Spong: $U ($S)\n", number, string,
       NULL);

This makes Describe() methods much easier to write. For example, BufferDescribe() might contain the following code:

WriteF(stream,
       "Buffer $P ($U) {\n", (WriteFP)buffer, (WriteFU)buffer->serial,
       "  base $A  init $A  alloc $A  limit $A\n",
       (WriteFA)buffer->base, (WriteFA)buffer->ap.init,
       (WriteFA)buffer->ap.alloc, (WriteFA)buffer->ap.limit,
       "  Pool $P\n",        (WriteFP)buffer->pool,
       "  Seg $P\n",         (WriteFP)buffer->seg,
       "  rank $U\n",        (WriteFU)buffer->rank,
       "  alignment $W\n",   (WriteFW)buffer->alignment,
       "  grey $B\n",        (WriteFB)buffer->grey,
       "  shieldMode $B\n",  (WriteFB)buffer->shieldMode,
       "  p $P  i $U\n",     (WriteFP)buffer->p, (WriteFU)buffer->i,
       "} Buffer $P ($U)\n", (WriteFP)buffer, (WriteFU)buffer->serial,
       NULL);

.types: For each format $X that WriteF() supports, there is a type defined in impl.h.mpmtypes WriteFX() which is the promoted version of that type. These are provided both to ensure promotion and to avoid any confusion about what type should be used in a cast. It is easy to check the casts against the formats to ensure that they correspond.

.types.future: It is possibly that this type set or similar may be used in future in some generalisation of varargs in the MPS.

.formats: The formats supported are as follows.

Code

Bame

Type

Example rendering

$A

address

Addr

000000019EF60010

$P

pointer

void *

000000019EF60100

$F

function

void *(*)()

0001D69E01000000 (see .f)

$S

string

char *

hello

$C

character

char

x

$W

word

ULongest

0000000000109AE0

$U

decimal

ULongest

42

$B

binary

ULongest

00000000000000001011011110010001

$$

dollar

–

$

Note that WriteFC is an int, because that is the default promotion of a char (see .types).

.snazzy: We should resist the temptation to make WriteF() an incredible snazzy output engine. We only need it for Describe() methods and assertion messages. At the moment it’s a very simple bit of code – let’s keep it that way.

.f: The F code is used for function pointers. ISO C forbids casting function pointers to other types, so the bytes of their representation are written sequentially, and may have a different endianness to other pointers. Could be smarter, or even look up function names, but see .snazzy.