mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-03-25 08:12:11 -07:00
Code Issues Projects Releases Wiki Activity

Mps: example code: 01hello.c

Browse source 
Copied from Perforce
 Change: 158078
 ServerID: perforce.ravenbrook.com
This commit is contained in:
Richard Kistruck 2006-04-10 15:01:46 +01:00
parent 80751e006d
commit a8ce3c25aa
1 changed files with 392 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

392
mps/example/01hello/index.txt Normal file
View file

@ -0,0 +1,392 @@
# Confidential: no. Readership: MPS users. Status: incomplete.
# Author: RHSK 2006-02-17. Copyright (C) 2006 Ravenbrook Limited
# <http://www.ravenbrook.com/>. All rights reserved.
# $Id$
# You can use rundoccode.py to automatically extract and run the
# code snippets in this document.
This document shows you how to call the MPS from your code.
To begin using the MPS, get a copy of the MPS-kit. (You've probably already got this, but if not look at <http://www.ravenbrook.com/>). You can skip the MPS-kit readme.txt file for now.
[Insert: instructions and layout of directory for the rest of this demo: where to put the MPS-kit]
The MPS is a software library, implemented in C. The types, functions, macros, constants, etc (collectively called "facilities") are declared in the MPS header files: your code must '#include' the MPS header files for the facilities you use. The facilities are implemented in the MPS libraries: your code must link with the libraries containing the facilities you use. The examples below show how to do this.
The "mps.h" header file
-----------------------
Here is a tiny C program to #include the "mps.h" header file and check that it compiles:
/* Demo File: 01checkmpsheader.c */
/* Simple C client of the MPS */
#include "mps.h"
int main(void)
{
mps_arena_class_t ArenaClassDemo;
return 0; /* success */
}
The "mps.h" header file declares the major (non-optional) MPS facilities, and all MPS client code needs to #include it. Find the "mps.h" header file in the "code" subdirectory of the MPS-kit.
For now, just put a copy of "mps.h" into a working directory where you can try the following examples. Now you can compile and run "01checkmpsheader.c". On Unix you might use:
% gcc 01checkmpsheader.c
% ./a.out && echo "success"
Choosing an arena class
-----------------------
The first step in using the MPS is to create an "arena". Inside this arena you will create "pools". Inside the pools you will create "objects". Arenas, pools, and objects are abstract data types: you must use MPS functions to create, change, and destroy them.
The arena abstracts the source of memory from which MPS will allocate: there are different classes of arena for different sorts of memory source. We will start with the "CL" arena class -- the "CL" stands for "client". A CL arena takes a big block of memory provided by the client (our demo program), and uses that as the source of memory in which to create pools and objects.
The code to create a CL arena will look roughly like this:
mps_arena_create(&ArenaDemo, mps_arena_class_cl(), arg1, arg2, ...)
Notice that the "CL" arena class is an abstract constant: the constant is not compiled into your code; instead, you call the MPS function mps_arena_class_cl() to obtain it. (Most MPS constants work this way; it avoids some versioning issues, and makes it easier to port the MPS to tricky platforms).
Additional MPS header files
---------------------------
The "mps_arena_class_cl" function is declared in the additional MPS header file "mpsacl.h" ("mpsa" stands for "MPS Arena class"). So put a copy of "mpsacl.h" into your working directory. The source code to use it looks like this:
/* Demo File: 02checkarenaclassheader.c */
/* Simple C client of the MPS */
#include "mps.h"
#include "mpsacl.h" /* for mps_arena_class_cl */
int main(void)
{
mps_arena_class_t ArenaClassDemo = NULL;
ArenaClassDemo = mps_arena_class_cl();
return 0; /* success */
}
To compile (but not link) this on Unix you might use the following command. (The "-c" tells gcc to stop after compilation).
% gcc -c 02checkarenaclassheader.c
However, when you try to link, it will fail because we don't have the MPS library to hand:
% gcc 02checkarenaclassheader.c
% # (this will fail)
The MPS library: "mps.a"
------------------------
The MPS library is available on many platforms: Windows, many Unixes, Mac OS X, etc. See the MPS-kit readme.txt file for details. For example, to compile the MPS library for Mac OS X, you might use this:
% cd mps-kit-1.106.1/code; make -f xcppgc.gmk VARIETY=ci mps.a
Briefly: "-f xcppgc.gmk" tells the buildsystem to use the makefile for Mac OS X ("xc"), for the PowerPC architecture ("pp"), using the GCC compiler ("gc"). "VARIETY=ci" tells it to build the 'cool internal' variety, which includes asserts and other run-time checks.
Object files and libraries are placed in a separate subdirectory, according to platform and variety: using the command above makes the library in "xcppgc/ci/mps.a". (The "mps.a" on the "make" command-line is a predefined target that the buildsystem recognises).
There is nothing magical about "mps.a": it is just a collection of object files built from MPS C source files. You can tailor your own collection with extras or omissions. The MPS-kit build system is configured to build an "mps.a" with the 'most commonly used' files, selecting the appropriate variant where there is a platform dependent choice.
However, when we try to link with it, we find that the MPS library itself has dependencies:
% gcc 02checkarenaclassheader.c mps-kit-1.106.1/code/xcppgc/ci/mps.a
% # (this will fail)
The MPS plinth: "mpsplan.a"
---------------------------
The dependency is because the MPS needs to call some functions in the client code (our demo program). The MPS can do this in two different ways: through the plinth interface, or through callbacks. The plinth interface is for general purpose utility functions, such as "mps_lib_memcpy" and "mps_lib_assert_fail". The client must provide these utility functions, and the MPS uses them. The idea here is that the MPS should not assume how the client wants these jobs to be done.
(Note: The MPS also makes some direct operating-system calls. Platform-specific source code files in the MPS use direct calls to cooperate with the operating-system in a platform-dependent manner, such as to write-protect pages of memory. These calls do not involve client code. In contrast, the plinth interface deals with platform-independent concepts that the client may have an interest in.)
We don't have to write our own plinth: the MPS-kit includes an example plinth that uses the standard C library. This example plinth is called "mpsplan.a". ("pl" means plinth; "an" means "ANSI", ie. the standard C library).
To build the example plinth for Mac OS X, use:
% cd mps-kit-1.106.1/code; make -f xcppgc.gmk VARIETY=ci mpsplan.a
Now we can link and run our simple demo file:
% gcc 02checkarenaclassheader.c mps-kit-1.106.1/code/xcppgc/ci/mps.a mps-kit-1.106.1/code/xcppgc/ci/mpsplan.a
% ./a.out && echo "success"
Recap
-----
We have now found and are using:
- the main "mps.h" header file;
- the additional MPS header file "mpsacl.h";
- (in "mpsacl.h") the identifier function "mps_arena_class_cl" for the "CL" arena class we want to use;
We have built and are using:
- the MPS library "mps.a";
- the example plinth "mpsplan.a".
Now we can start to use more MPS functions. In the next three sections we will create an arena (of class "CL"), create a pool (of class "MV"), and then allocate some memory.
Creating an arena
-----------------
Look up the reference manual entry for mps_arena_class_cl() at <http://www.ravenbrook.com/project/mps/master/manual/reference/#mps_arena_class_cl>. The notes and example code in the manual entry describe the additional parameters that we need to pass to "mps_arena_create()". For a "CL" class arena, we first allocate a big block of memory, and then call mps_arena_create passing the count of bytes and a pointer to the first byte:
/* Demo File: 03arena_create.c */
/* Simple C client of the MPS */
#include <stdlib.h> /* for malloc */
#include <stdio.h> /* for printf */
#include "mps.h"
#include "mpsacl.h" /* for mps_arena_class_cl */
int main(void)
{
void *pBlock = NULL;
size_t cbBlock = 1024 * 1024;
mps_arena_t ArenaDemo = NULL;
mps_res_t res;
pBlock = malloc(cbBlock);
if(pBlock == NULL) {
printf("malloc failed!\n");
exit(1);
}
res = mps_arena_create(&ArenaDemo, mps_arena_class_cl(), cbBlock, pBlock);
switch (res) {
case MPS_RES_OK:
break;
case MPS_RES_MEMORY:
printf("mps_arena_create: cbBlock too small\n");
exit(2);
case MPS_RES_FAIL:
printf("mps_arena_create: refused; see MPS reference manual\n");
exit(2);
}
/* rest of program */
printf("Success.\n");
return 0;
}
To run this file:
% gcc 03arena_create.c mps-kit-1.106.1/code/xcppgc/ci/mps.a mps-kit-1.106.1/code/xcppgc/ci/mpsplan.a
% ./a.out
Creating a pool
---------------
Before allocating memory, we must create a "pool". A pool abstracts a collection of objects that are managed in the same way. The "way an object is managed" means the protocol used by the client and MPS to create, maintain, and destroy the object.
We will create a pool of the "MV" pool class. "MV" roughly stands for "manual, variable". "Manual" means the client explicitly tells the MPS when to free the object (in contrast to an "automatic" protocol, ie. with automatic garbage collection, where the client never calls free). "Variable" means the pool can hold objects of varying sizes.
The functions we need are "mps_class_mv()" and "mps_pool_create()" -- these are analogous to the "mps_arena_class_cl" and "mps_arena_create" we needed for creating an arena. [Note the inconsistent naming: "mps_class_mv" should really be called "mps_pool_class_mv".]
Put a copy of "mpscmv.h" into your working directory ("mpsc" stands for "MPS (pool) Class"; "MV" is the name of the pool class). It declares the "mps_class_mv" function, and some useful pool-class-specific functions. We will use "mps_class_mv()" and "mps_mv_free_size()".
If you attempt to look up the reference manual entries for "mps_class_mv()" and "mps_pool_create()", you will find they are missing. [Section 4][] of the reference manual lists them as valid client-callable functions, but currently undocumented. Don't despair. Look in the "code" subdirectory of the MPS-kit, and find the file "poolmv.h".
[Section 4]: <http://www.ravenbrook.com/project/mps/master/manual/reference/#section-4>
[RefMan: document "mps_class_mv" and and "mps_pool_create"]
The "poolmv.h" file is internal to the MPS, and contains part of the implementation of the "MV" pool class. The MPS tries hard to keep its external interface (header files beginning "mps...") separate from its internal details. Where the external documentation is lacking, you can look at internal materials such as design documentation, implementation files, and module test files, but be aware that you have crossed over to the 'internal world' of the MPS. Two differences you may notice in internal code are that the types used are different, and function names are different. It should go without saying that your client code should never rely on the particular details of the MPS implementation. If you (as an MPS user writing client code) find yourself needing to look inside the MPS implementation, that suggests there is a fault in the external documentation: please contact us and let us know.
The parameters used to create a pool of class "MV" are discussed in the comments at the top of the "poolmv.h" file. When creating a pool of class "MV", mps_pool_create requires three extra arguments, which hold tuning parameters that help the pool to perform its tasks efficiently. The first and third arguments relate to the size of the pool; the second argument relates to the size of objects in the pool. (See the comments in "poolmv.h" for more detail).
All three arguments are counts of bytes. The correct type for client code to specify counts of bytes is "size_t". (Note that it is incorrect to use the "Size" type -- this is an MPS-internal type).
[How do I know that "size_t" is the correct type? Boo for varargs.]
Finally, note that:
"mpscmv.h" is an 'external' header file -- part of the interface to the MPS, which you #include.
"poolmv.h" is an 'internal' header file, *not* a client-visible MPS header: your code should not (and does not need to) #include it.
Here is code to create an arena, and create an MV class pool within it:
/* Demo File: 04pool_create.c */
/* Simple C client of the MPS */
#include <stdlib.h> /* for malloc */
#include <stdio.h> /* for printf */
#include "mps.h"
#include "mpsacl.h" /* for mps_arena_class_cl */
#include "mpscmv.h" /* for mps_class_mv */
int main(void)
{
void *pBlock = NULL;
size_t cbBlock = 1024 * 1024;
mps_arena_t ArenaDemo = NULL;
mps_pool_t PoolDemo = NULL;
mps_res_t res;
{
/* Create arena */
pBlock = malloc(cbBlock);
if(pBlock == NULL) {
printf("malloc failed!\n");
exit(1);
}
res = mps_arena_create(&ArenaDemo, mps_arena_class_cl(), cbBlock, pBlock);
if (res != MPS_RES_OK) {
printf("mps_arena_create: failed with res %d.\n", res);
exit(2);
}
}
{
/* Create pool */
size_t cbPoolExtend = 1024;
size_t cbObjectAvg = 32;
size_t cbPoolMax = 64 * 1024;
size_t cbPoolFree = 0;
res = mps_pool_create(&PoolDemo, ArenaDemo, mps_class_mv(), cbPoolExtend, cbObjectAvg, cbPoolMax);
if (res != MPS_RES_OK) {
printf("mps_pool_create: failed with res %d.\n", res);
exit(2);
}
cbPoolFree = mps_mv_free_size(PoolDemo);
printf("PoolDemo has %lu bytes free.\n", (unsigned long)cbPoolFree);
}
/* rest of program */
{
printf("Success.\n");
return 0;
}
}
Compiling and running this produces the possibly surprising result that the freshly-created pool has zero (0) bytes free:
% gcc 04pool_create.c mps-kit-1.106.1/code/xcppgc/ci/mps.a mps-kit-1.106.1/code/xcppgc/ci/mpsplan.a
% ./a.out
% # (should say: "PoolDemo has 0 bytes free.")
Pools request chunks of storage from their arena when they need it, and return it afterwards. The MV pool class code does not request storage until the first object is allocated; this is why PoolDemo has 0 bytes free initially: it has not yet claimed memory from the arena.
Allocating some memory
----------------------
Finally, we can now allocate some memory! We use the simple "mps_alloc" function, and store the text "hello, world" in the memory, and print it out.
/* Demo File: 05alloc.c */
/* Simple C client of the MPS */
#include <stdlib.h> /* for malloc */
#include <stdio.h> /* for printf */
#include <string.h> /* for strcpy */
#include "mps.h"
#include "mpsacl.h" /* for mps_arena_class_cl */
#include "mpscmv.h" /* for mps_class_mv */
static void reportPoolmv(mps_pool_t Pool)
{
size_t cbPoolFree = mps_mv_free_size(Pool);
printf("Pool has %lu bytes free.\n", (unsigned long)cbPoolFree);
}
int main(void)
{
void *pBlock = NULL;
size_t cbBlock = 1024 * 1024;
mps_arena_t ArenaDemo = NULL;
mps_pool_t PoolDemo = NULL;
mps_res_t res;
{
/* Create arena */
pBlock = malloc(cbBlock);
if(pBlock == NULL) {
printf("malloc failed!\n");
exit(1);
}
res = mps_arena_create(&ArenaDemo, mps_arena_class_cl(), cbBlock, pBlock);
if (res != MPS_RES_OK) {
printf("mps_arena_create: failed with res %d.\n", res);
exit(2);
}
}
{
/* Create pool */
size_t cbPoolExtend = 1024;
size_t cbObjectAvg = 32;
size_t cbPoolMax = 64 * 1024;
size_t cbPoolFree = 0;
res = mps_pool_create(&PoolDemo, ArenaDemo, mps_class_mv(), cbPoolExtend, cbObjectAvg, cbPoolMax);
if (res != MPS_RES_OK) {
printf("mps_pool_create: failed with res %d.\n", res);
exit(2);
}
reportPoolmv(PoolDemo);
}
{
/* Allocate memory */
size_t cbBuffer = 100;
void *p = NULL;
res = mps_alloc(&p, PoolDemo, cbBuffer);
if (res != MPS_RES_OK) {
printf("mps_alloc: failed with res %d.\n", res);
exit(2);
}
reportPoolmv(PoolDemo);
{
/* Show that it really is memory */
char *pbBuffer = (char *)p;
strcpy(pbBuffer, "hello--world\n");
pbBuffer[5] = ',';
pbBuffer[6] = ' ';
printf(pbBuffer);
}
}
printf("Successfully allocated some memory with mps_alloc(), in an MV pool, in a CL arena.\n");
return 0;
}
To compile and run this:
% gcc 05alloc.c mps-kit-1.106.1/code/xcppgc/ci/mps.a mps-kit-1.106.1/code/xcppgc/ci/mpsplan.a
% ./a.out
% # (should say: "PoolDemo has 0 bytes free.")
% # (and then: "PoolDemo has NNNN bytes free.", where NNNN depends on platform.)
% # (and then: "hello, world")
[END]