diff --git a/mps/example/hello-world/index.txt b/mps/example/hello-world/index.txt deleted file mode 100644 index 6820c9dc4bb..00000000000 --- a/mps/example/hello-world/index.txt +++ /dev/null @@ -1,613 +0,0 @@ -# Confidential: no. Readership: MPS users. Status: complete. -# Author: RHSK 2006-02-17. Copyright (C) 2006 Ravenbrook Limited -# . All rights reserved. -# See end of file for license. -# $Id$ - - -This is the "hello-world" example; it shows you how to call the MPS from -your code. - -To begin, get a copy of the MPS-kit from: - - -Unpack the MPS-kit. (You don't need to compile anything yet, so you can -skip the MPS-kit readme.txt file for now). - -The MPS-kit unpacks to a directory named "mps-kit-1.108.2" (or similar), -with subdirectories like this: - - mps-kit-1.108.2/ - code/ - design/ - example/ - manual/ - procedure/ - test/ - tool/ - -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_t ArenaDemo; - 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: - - mps-kit-1.108.2/code/mps.h - -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_t ArenaDemo; - 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.108.2/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.108.2/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.108.2/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.108.2/code/xcppgc/ci/mps.a mps-kit-1.108.2/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 -. 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 /* for malloc */ - #include /* 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.108.2/code/xcppgc/ci/mps.a mps-kit-1.108.2/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". - -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". (This is not documented; -it ought to be documented under "mps_class_mv" in the reference manual. -Note that it is incorrect to use the "Size" type -- this is an -MPS-internal type.) - -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 /* for malloc */ - #include /* 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.108.2/code/xcppgc/ci/mps.a mps-kit-1.108.2/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 /* for malloc */ - #include /* for printf */ - #include /* 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( - "Success: The hello-world example code successfully allocated\n" - "some memory using mps_alloc(), in an MV pool, in a CL arena.\n" - ); - return 0; - } - -To compile and run this: - - % gcc 05alloc.c mps-kit-1.108.2/code/xcppgc/ci/mps.a mps-kit-1.108.2/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") - -That's the end of this example code. - - -DOCUMENT HISTORY - -2006-02-17 RHSK Created from scratch, referencing version/1.106.1 -2006-04-10 RHSK Tidy for release; refer to version/1.106.2 -2006-12-13 RHSK Version 1.107 -2007-07-06 RHSK Version 1.108 -2007-12-21 RHSK Release 1.108.1 -2008-05-01 RHSK Release 1.108.2 - - -COPYRIGHT AND LICENSE - -Copyright (C) 2006,2007 Ravenbrook Limited . -All rights reserved. This is an open source license. Contact -Ravenbrook for commercial licensing options. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -1. Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright -notice, this list of conditions and the following disclaimer in the -documentation and/or other materials provided with the distribution. - -3. Redistributions in any form must be accompanied by information on how -to obtain complete source code for this software and any -accompanying software that uses this software. The source code must -either be included in the distribution or be available for no more than -the cost of distribution plus a nominal fee, and must be freely -redistributable under reasonable conditions. For an executable file, -complete source code means the source code for all modules it contains. -It does not include source code for modules or files that typically -accompany the major components of the operating system on which the -executable file runs. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS -IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED -TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE, OR NON-INFRINGEMENT, ARE DISCLAIMED. IN NO EVENT SHALL THE -COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF -USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF -THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -[END] diff --git a/mps/example/index.html b/mps/example/index.html deleted file mode 100644 index e44a162b0d8..00000000000 --- a/mps/example/index.html +++ /dev/null @@ -1,139 +0,0 @@ - - - - - - - - -Example Code - - - - - - - - -

1. Introduction

- -

This is the catalogue of example code for the Memory Pool System product.

- -

The example code shows you how to write code that uses the MPS. (In other words, how to use facilities in "mps.h").

- -

The simplest example — "hello-world" — gets you started using the MPS to allocate some memory to store and print the text "hello, world".

- -

This document is not confidential. The readership of this document is developers of client code that uses the MPS interface.

- -

Related documents:

- - - -

2. Example Code

- - - - - - - - -
hello-world/simplest call to mps_alloc() — START HERE!
- - -

A. References

- - - - -

B. Document History

- - - - - - - - - -
2006-04-10RHSKCreated (based on ../manual/index.txt).
- - -

C. Copyright and License

- -

This document is copyright © 2006 Ravenbrook Limited. All rights reserved. This is an open source license. Contact Ravenbrook for commercial licensing options.

- -

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- -
    - -
  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    2. - -
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    3. - -
  3. Redistributions in any form must be accompanied by information on how to obtain complete source code for this software and any accompanying software that uses this software. The source code must either be included in the distribution or be available for no more than the cost of distribution plus a nominal fee, and must be freely redistributable under reasonable conditions. For an executable file, complete source code means the source code for all modules it contains. It does not include source code for modules or files that typically accompany the major components of the operating system on which the executable file runs.
    4. - -
- -

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement, are disclaimed. In no event shall the copyright holders and contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

- - -
- - - - - -