Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-16 17:24:23 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merging branch/2023-03-09/sig-design-tidy for github pull request <https://github.com/ravenbrook/mps/pull/193>.

Browse source 
GitHub-reference: https://github.com/Ravenbrook/mps/issues/193
This commit is contained in:
Richard Brooksby 2023-03-13 20:17:31 +00:00
commit 601976ff80
42 changed files with 163 additions and 130 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
mps/code/abq.h
View file

@ -43,6 +43,7 @@ extern void ABQIterate(ABQ abq, ABQVisitor visitor, void *closure);
typedef struct ABQStruct
{
Sig sig; /* design.mps.sig.field */
Count elements;
Size elementSize;
Index in;
@ -54,8 +55,6 @@ typedef struct ABQStruct
METER_DECL(pop)
METER_DECL(peek)
METER_DECL(delete)
Sig sig;
} ABQStruct;
#endif /* abq_h */

4
mps/code/arenacl.c
View file

@ -30,7 +30,7 @@ DECLARE_CLASS(Arena, ClientArena, AbstractArena);
typedef struct ClientArenaStruct {
ArenaStruct arenaStruct; /* generic arena structure */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} ClientArenaStruct;
typedef struct ClientArenaStruct *ClientArena;
@ -45,7 +45,7 @@ typedef struct ClientChunkStruct {
ChunkStruct chunkStruct; /* generic chunk */
Size freePages; /* number of free pages in chunk */
Addr pageBase; /* base of first managed page in chunk */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} ClientChunkStruct;
#define ClientChunk2Chunk(clchunk) (&(clchunk)->chunkStruct)

4
mps/code/arenavm.c
View file

@ -45,7 +45,7 @@ typedef struct VMChunkStruct {
VMStruct vmStruct; /* virtual memory descriptor */
Addr overheadMappedLimit; /* limit of pages mapped for overhead */
SparseArrayStruct pages; /* to manage backing store of page table */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} VMChunkStruct;
#define VMChunk2Chunk(vmchunk) (&(vmchunk)->chunkStruct)
@ -78,7 +78,7 @@ typedef struct VMArenaStruct { /* VM arena structure */
ArenaVMContractedCallback contracted;
MFSStruct cbsBlockPoolStruct; /* stores blocks for CBSs */
CBSStruct spareLandStruct; /* spare memory */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} VMArenaStruct;
#define VMArenaVM(vmarena) (&(vmarena)->vmStruct)

2
mps/code/arg.h
View file

@ -22,7 +22,7 @@
#define KeySig ((Sig)0x519CE111) /* SIGnature KEYyy */
typedef struct mps_key_s {
Sig sig;
Sig sig; /* design.mps.sig.field */
const char *name;
Bool (*check)(Arg arg);
} KeyStruct;

2
mps/code/boot.h
View file

@ -16,7 +16,7 @@
typedef struct BootBlockStruct
{
Sig sig;
Sig sig; /* design.mps.sig.field */
void *base;
void *alloc;
void *limit;

2
mps/code/dbgpool.h
View file

@ -42,7 +42,7 @@ typedef PoolDebugOptionsStruct *PoolDebugOptions;
#define PoolDebugMixinSig ((Sig)0x519B0DB9) /* SIGnature POol DeBuG */
typedef struct PoolDebugMixinStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
const struct AddrStruct *fenceTemplate;
Size fenceSize;
const struct AddrStruct *freeTemplate;

2
mps/code/lockan.c
View file

@ -18,7 +18,7 @@ SRCID(lockan, "$Id$");
typedef struct LockStruct { /* ANSI fake lock structure */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
unsigned long claims; /* # claims held by owner */
} LockStruct;

2
mps/code/lockix.c
View file

@ -51,7 +51,7 @@ SRCID(lockix, "$Id$");
*/
typedef struct LockStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
unsigned long claims; /* # claims held by owner */
pthread_mutex_t mut; /* the mutex itself */
} LockStruct;

2
mps/code/lockw3.c
View file

@ -35,7 +35,7 @@ SRCID(lockw3, "$Id$");
/* .lock.win32: Win32 lock structure; uses CRITICAL_SECTION */
typedef struct LockStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
unsigned long claims; /* # claims held by the owning thread */
CRITICAL_SECTION cs; /* Win32's recursive lock thing */
} LockStruct;

6
mps/code/locus.h
View file

@ -41,7 +41,7 @@ typedef struct GenDescStruct *GenDesc;
#define GenDescSig ((Sig)0x5199E4DE) /* SIGnature GEN DEsc */
typedef struct GenDescStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Serial serial; /* serial number within arena */
ZoneSet zones; /* zoneset for this generation */
Size capacity; /* capacity in bytes */
@ -58,7 +58,7 @@ typedef struct GenDescStruct {
#define PoolGenSig ((Sig)0x519B009E) /* SIGnature POOl GEn */
typedef struct PoolGenStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
Pool pool; /* pool this belongs to */
GenDesc gen; /* generation this belongs to */
/* link in ring of all PoolGen's in this GenDesc (locus) */
@ -81,7 +81,7 @@ typedef struct PoolGenStruct {
#define ChainSig ((Sig)0x519C8A14) /* SIGnature CHAIN */
typedef struct mps_chain_s {
Sig sig;
Sig sig; /* design.mps.sig.field */
Arena arena;
RingStruct chainRing; /* list of chains in the arena */
size_t genCount; /* number of generations */

57
mps/code/mpmst.h
View file

@ -41,10 +41,7 @@
* CLASS(ABCPool) returns a PoolClass pointing to a PoolClassStruct of
* methods which implement the memory management policy for pool class
* ABC.
*
* .class.end-sig: The class structure has a signature at the end. This
* causes the compiler to complain if the class structure is extended
* without modifying static initializers. */
*/
#define PoolClassSig ((Sig)0x519C7A55) /* SIGnature pool CLASS */
@ -68,7 +65,7 @@ typedef struct mps_pool_class_s {
PoolDebugMixinMethod debugMixin; /* find the debug mixin, if any */
PoolSizeMethod totalSize; /* total memory allocated from arena */
PoolSizeMethod freeSize; /* free memory (unused by client program) */
Sig sig; /* .class.end-sig */
Sig sig; /* design.mps.sig.field.end.outer */
} PoolClassStruct;
@ -86,7 +83,7 @@ typedef struct mps_pool_class_s {
typedef struct mps_pool_s { /* generic structure */
InstStruct instStruct;
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Serial serial; /* from arena->poolSerial */
Arena arena; /* owning arena */
RingStruct arenaRing; /* link in list of pools in arena */
@ -122,7 +119,7 @@ typedef struct MFSStruct { /* MFS outer structure */
Size total; /* total size allocated from arena */
Size free; /* free space in pool */
RingStruct extentRing; /* ring of extents in pool */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} MFSStruct;
@ -135,7 +132,7 @@ typedef struct MFSStruct { /* MFS outer structure */
#define MessageClassSig ((Sig)0x519359c1) /* SIGnature MeSsaGe CLass */
typedef struct MessageClassStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
const char *name; /* Human readable Class name */
MessageType type; /* Message Type */
@ -164,7 +161,7 @@ typedef struct MessageClassStruct {
* <design/message#.message.struct>. */
typedef struct mps_message_s {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Arena arena; /* owning arena */
MessageClass klass; /* Message Class Structure */
Clock postedClock; /* mps_clock() at post time, or 0 */
@ -208,7 +205,7 @@ typedef struct SegClassStruct {
SegFixMethod fixEmergency; /* as fix, no failure allowed */
SegReclaimMethod reclaim; /* reclaim dead objects after tracing */
SegWalkMethod walk; /* walk over a segment */
Sig sig; /* .class.end-sig */
Sig sig; /* design.mps.sig.field.end.outer */
} SegClassStruct;
@ -221,7 +218,7 @@ typedef struct SegClassStruct {
typedef struct SegStruct { /* segment structure */
InstStruct instStruct;
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field */
Tract firstTract; /* first tract of segment */
RingStruct poolRing; /* link in list of segs in pool */
Addr limit; /* limit of segment */
@ -250,7 +247,7 @@ typedef struct GCSegStruct { /* GC segment structure */
RefSet summary; /* summary of references out of seg */
Buffer buffer; /* non-NULL if seg is buffered */
RingStruct genRing; /* link in list of segs in gen */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} GCSegStruct;
@ -264,7 +261,7 @@ typedef struct GCSegStruct { /* GC segment structure */
#define LocusPrefSig ((Sig)0x51970CB6) /* SIGnature LOCus PRef */
typedef struct LocusPrefStruct { /* locus placement preferences */
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field */
Bool high; /* high or low */
ZoneSet zones; /* preferred zones */
ZoneSet avoid; /* zones to avoid */
@ -292,7 +289,7 @@ typedef struct BufferClassStruct {
BufferRankSetMethod rankSet; /* rank set of buffer */
BufferSetRankSetMethod setRankSet; /* change rank set of buffer */
BufferReassignSegMethod reassignSeg; /* change seg of attached buffer */
Sig sig; /* .class.end-sig */
Sig sig; /* design.mps.sig.field.end.outer */
} BufferClassStruct;
@ -310,7 +307,7 @@ typedef struct BufferClassStruct {
typedef struct BufferStruct {
InstStruct instStruct;
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Serial serial; /* from pool->bufferSerial */
Arena arena; /* owning arena */
Pool pool; /* owning pool */
@ -339,7 +336,7 @@ typedef struct SegBufStruct {
BufferStruct bufferStruct; /* superclass fields must come first */
RankSet rankSet; /* ranks of references being created */
Seg seg; /* segment being buffered */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} SegBufStruct;
@ -353,7 +350,7 @@ typedef struct SegBufStruct {
#define FormatSig ((Sig)0x519F63A2) /* Signature FoRMAT */
typedef struct mps_fmt_s {
Sig sig;
Sig sig; /* design.mps.sig.field */
Serial serial; /* from arena->formatSerial */
Arena arena; /* owning arena */
RingStruct arenaRing; /* formats are attached to the arena */
@ -399,7 +396,7 @@ typedef struct mps_fmt_s {
#define ScanStateSig ((Sig)0x5195CA45) /* SIGnature SCAN State */
typedef struct ScanStateStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
struct mps_ss_s ss_s; /* .ss <http://bash.org/?400459> */
Arena arena; /* owning arena */
mps_fmt_scan_t formatScan; /* callback for scanning formatted objects */
@ -428,7 +425,7 @@ typedef struct ScanStateStruct {
#define TraceSig ((Sig)0x51924ACE) /* SIGnature TRACE */
typedef struct TraceStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
TraceId ti; /* index into TraceSets */
Arena arena; /* owning arena */
TraceStartWhy why; /* why the trace began */
@ -492,7 +489,7 @@ typedef struct mps_arena_class_s {
ArenaCompactMethod compact;
ArenaPagesMarkAllocatedMethod pagesMarkAllocated;
ArenaChunkPageMappedMethod chunkPageMapped;
Sig sig;
Sig sig; /* design.mps.sig.field.end.outer */
} ArenaClassStruct;
@ -506,7 +503,7 @@ typedef struct mps_arena_class_s {
#define GlobalsSig ((Sig)0x519970BA) /* SIGnature GLOBAls */
typedef struct GlobalsStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
/* general fields <code/global.c> */
RingStruct globalRing; /* node in global ring of arenas */
@ -564,7 +561,7 @@ typedef struct LandClassStruct {
LandFindMethod findLast; /* find last range of given size */
LandFindMethod findLargest; /* find largest range */
LandFindInZonesMethod findInZones; /* find first range of given size in zone set */
Sig sig; /* .class.end-sig */
Sig sig; /* design.mps.sig.field.end.outer */
} LandClassStruct;
@ -577,7 +574,7 @@ typedef struct LandClassStruct {
typedef struct LandStruct {
InstStruct instStruct;
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Arena arena; /* owning arena */
Align alignment; /* alignment of addresses */
Bool inLand; /* prevent reentrance */
@ -604,7 +601,7 @@ typedef struct CBSStruct {
Size size; /* total size of ranges in CBS */
/* meters for sizes of search structures at each op */
METER_DECL(treeSearch)
Sig sig; /* .class.end-sig */
Sig sig; /* design.mps.sig.field.end.outer */
} CBSStruct;
@ -622,7 +619,7 @@ typedef struct FailoverStruct {
LandStruct landStruct; /* superclass fields come first */
Land primary; /* use this land normally */
Land secondary; /* but use this one if primary fails */
Sig sig; /* .class.end-sig */
Sig sig; /* design.mps.sig.field.end.outer */
} FailoverStruct;
@ -643,7 +640,7 @@ typedef struct FreelistStruct {
FreelistBlock list; /* first block in list or NULL if empty */
Count listSize; /* number of blocks in list */
Size size; /* total size of ranges in list */
Sig sig; /* .class.end-sig */
Sig sig; /* design.mps.sig.field.end.outer */
} FreelistStruct;
@ -669,7 +666,7 @@ typedef struct SortStruct {
#define ShieldSig ((Sig)0x519581E1) /* SIGnature SHEILd */
typedef struct ShieldStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
BOOLFIELD(inside); /* <design/shield#.def.inside> */
BOOLFIELD(suspended); /* mutator suspended? */
BOOLFIELD(queuePending); /* queue insertion pending? */
@ -692,7 +689,7 @@ typedef struct ShieldStruct {
#define HistorySig ((Sig)0x51981520) /* SIGnature HISTOry */
typedef struct HistoryStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Epoch epoch; /* <design/arena#.ld.epoch> */
RefSet prehistory; /* <design/arena#.ld.prehistory> */
RefSet history[LDHistoryLENGTH]; /* <design/arena#.ld.history> */
@ -724,7 +721,7 @@ typedef struct MVFFStruct { /* MVFF pool outer structure */
FailoverStruct foStruct; /* free memory (fail-over mechanism) */
Bool firstFit; /* as opposed to last fit */
Bool slotHigh; /* prefers high part of large block */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} MVFFStruct;
@ -819,7 +816,7 @@ typedef struct mps_arena_s {
void *stackWarm; /* NULL or stack pointer warmer than
mutator state. */
Sig sig;
Sig sig; /* design.mps.sig.field.end.outer */
} ArenaStruct;

4
mps/code/mpmtypes.h
View file

@ -26,7 +26,7 @@
/* TYPES */
typedef unsigned long Sig; /* <design/sig> */
typedef unsigned long Sig; /* design.mps.sig */
typedef int Res; /* <design/type#.res> */
typedef void (*Fun)(void); /* <design/type#.fun> */
@ -262,7 +262,7 @@ typedef Res (*LandFindInZonesMethod)(Bool *foundReturn, Range rangeReturn, Range
/* CONSTANTS */
/* <design/sig> */
/* design.mps.sig */
#define SigInvalid ((Sig)0x51915BAD) /* SIGnature IS BAD */
#define SizeMAX ((Size)-1)

2
mps/code/nailboard.h
View file

@ -22,7 +22,7 @@ typedef struct NailboardStruct *Nailboard;
* each function call by the owner.) newNails would fit in 1 bit.
*/
typedef struct NailboardStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
RangeStruct range; /* range of addresses covered by nailboard */
Count levels; /* number of levels */
Shift alignShift; /* shift due to address alignment */

2
mps/code/poolabs.c
View file

@ -105,7 +105,7 @@ Res PoolAbsInit(Pool pool, Arena arena, PoolClass klass, ArgList args)
pool->serial = ArenaGlobals(arena)->poolSerial;
++ArenaGlobals(arena)->poolSerial;
/* Initialise signature last; see <design/sig> */
/* Initialise signature last; see design.mps.sig.init */
SetClassOfPoly(pool, CLASS(AbstractPool));
pool->sig = PoolSig;
AVERT(Pool, pool);

8
mps/code/poolamc.c
View file

@ -56,7 +56,7 @@ typedef struct amcGenStruct {
PoolGenStruct pgen;
RingStruct amcRing; /* link in list of gens in pool */
Buffer forward; /* forwarding buffer */
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} amcGenStruct;
#define amcGenAMC(amcgen) MustBeA(AMCZPool, (amcgen)->pgen.pool)
@ -113,7 +113,7 @@ typedef struct amcSegStruct {
BOOLFIELD(accountedAsBuffered); /* .seg.accounted-as-buffered */
BOOLFIELD(old); /* .seg.old */
BOOLFIELD(deferred); /* .seg.deferred */
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} amcSegStruct;
@ -422,7 +422,7 @@ typedef struct AMCStruct { /* <design/poolamc#.struct> */
amcPinnedFunction pinned; /* function determining if block is pinned */
Size extendBy; /* segment size to extend pool by */
Size largeSize; /* min size of "large" segments */
Sig sig; /* <design/pool#.outer-structure.sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} AMCStruct;
@ -457,7 +457,7 @@ typedef struct amcBufStruct {
SegBufStruct segbufStruct; /* superclass fields must come first */
amcGen gen; /* The AMC generation */
Bool forHashArrays; /* allocates hash table arrays, see AMCBufferFill */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} amcBufStruct;

4
mps/code/poolams.h
View file

@ -48,7 +48,7 @@ typedef struct AMSStruct {
AMSSegsDestroyFunction segsDestroy;
AMSSegClassFunction segClass;/* fn to get the class for segments */
Bool shareAllocTable; /* the alloc table is also used as white table */
Sig sig; /* <design/pool#.outer-structure.sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} AMSStruct;
@ -69,7 +69,7 @@ typedef struct AMSSegStruct {
Bool colourTablesInUse;/* the colour tables are in use */
BT nonwhiteTable; /* set if grain not white */
BT nongreyTable; /* set if not first grain of grey object */
Sig sig;
Sig sig; /* design.mps.sig.field.end.outer */
} AMSSegStruct;

4
mps/code/poolawl.c
View file

@ -102,7 +102,7 @@ typedef struct AWLPoolStruct {
Count succAccesses; /* number of successive single accesses */
FindDependentFunction findDependent; /* to find a dependent object */
awlStatTotalStruct stats;
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} AWLPoolStruct, *AWL;
@ -138,7 +138,7 @@ typedef struct AWLSegStruct {
Count oldGrains; /* grains allocated prior to last collection */
Count singleAccesses; /* number of accesses processed singly */
awlStatSegStruct stats;
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} AWLSegStruct, *AWLSeg;
DECLARE_CLASS(Seg, AWLSeg, MutatorSeg);

4
mps/code/poollo.c
View file

@ -25,7 +25,7 @@ typedef struct LOStruct {
PoolStruct poolStruct; /* generic pool structure */
PoolGenStruct pgenStruct; /* generation representing the pool */
PoolGen pgen; /* NULL or pointer to pgenStruct */
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} LOStruct;
typedef LO LOPool;
@ -59,7 +59,7 @@ typedef struct LOSegStruct {
Count bufferedGrains; /* grains in buffers */
Count newGrains; /* grains allocated since last collection */
Count oldGrains; /* grains allocated prior to last collection */
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} LOSegStruct;

6
mps/code/poolmrg.c
View file

@ -107,7 +107,7 @@ typedef struct MRGStruct {
RingStruct freeRing; /* <design/poolmrg#.poolstruct.free> */
RingStruct refRing; /* <design/poolmrg#.poolstruct.refring> */
Size extendBy; /* <design/poolmrg#.extend> */
Sig sig; /* <code/mps.h#sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} MRGStruct;
typedef MRG MRGPool;
@ -143,14 +143,14 @@ typedef struct MRGRefSegStruct *MRGRefSeg;
typedef struct MRGLinkSegStruct {
SegStruct segStruct; /* superclass fields must come first */
MRGRefSeg refSeg; /* <design/poolmrg#.mrgseg.link.refseg> */
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} MRGLinkSegStruct;
typedef struct MRGRefSegStruct {
GCSegStruct gcSegStruct; /* superclass fields must come first */
RingStruct mrgRing; /* <design/poolmrg#.mrgseg.ref.segring> */
MRGLinkSeg linkSeg; /* <design/poolmrg#.mrgseg.ref.linkseg> */
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} MRGRefSegStruct;

2
mps/code/poolmv2.c
View file

@ -132,7 +132,7 @@ typedef struct MVTStruct
METER_DECL(exceptionSplinters)
METER_DECL(exceptionReturns)
Sig sig;
Sig sig; /* design.mps.sig.field.end.outer */
} MVTStruct;

6
mps/code/poolsnc.c
View file

@ -34,7 +34,7 @@ SRCID(poolsnc, "$Id$");
typedef struct SNCStruct {
PoolStruct poolStruct;
Seg freeSegs;
Sig sig;
Sig sig; /* design.mps.sig.field.end.outer */
} SNCStruct, *SNC;
#define PoolSNC(pool) PARENT(SNCStruct, poolStruct, (pool))
@ -78,7 +78,7 @@ typedef struct SNCBufStruct *SNCBuf;
typedef struct SNCBufStruct {
SegBufStruct segBufStruct; /* superclass fields must come first */
Seg topseg; /* The segment chain head -- may be NULL */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} SNCBufStruct;
@ -182,7 +182,7 @@ typedef struct SNCSegStruct *SNCSeg;
typedef struct SNCSegStruct {
GCSegStruct gcSegStruct; /* superclass fields must come first */
SNCSeg next; /* Next segment in chain, or NULL */
Sig sig;
Sig sig; /* design.mps.sig.field.end.outer */
} SNCSegStruct;
#define SegSNCSeg(seg) ((SNCSeg)(seg))

2
mps/code/prmcix.h
View file

@ -15,7 +15,7 @@
#include <ucontext.h> /* ucontext_t */
typedef struct MutatorContextStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
MutatorContextVar var; /* Discriminator. */
siginfo_t *info; /* Signal info, if stopped by protection
* fault; NULL if stopped by thread manager. */

2
mps/code/prmcw3.h
View file

@ -13,7 +13,7 @@
#include "mpswin.h"
typedef struct MutatorContextStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
MutatorContextVar var; /* Union discriminator */
union {
LPEXCEPTION_POINTERS ep; /* Windows Exception Pointers */

2
mps/code/prmcxc.h
View file

@ -21,7 +21,7 @@
#endif
typedef struct MutatorContextStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
MutatorContextVar var; /* Discriminator. */
Addr address; /* Fault address, if stopped by protection
* fault; NULL if stopped by thread manager. */

2
mps/code/protocol.h
View file

@ -186,7 +186,7 @@ typedef void (*FinishMethod)(Inst inst);
typedef struct InstClassStruct {
InstStruct instStruct; /* classes are instances of kinds */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
ClassName name; /* human readable name such as "Land" */
InstClass superclass; /* pointer to direct superclass */
ClassLevel level; /* distance from root of class hierarchy */

2
mps/code/pthrdext.h
View file

@ -30,7 +30,7 @@ typedef struct PThreadextStruct *PThreadext;
*/
typedef struct PThreadextStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
pthread_t id; /* Thread ID */
MutatorContext context; /* context if suspended */
RingStruct threadRing; /* ring of suspended threads */

2
mps/code/root.c
View file

@ -23,7 +23,7 @@ typedef union AreaScanUnion {
} AreaScanUnion;
typedef struct RootStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
Serial serial; /* from arena->rootSerial */
Arena arena; /* owning arena */
RingStruct arenaRing; /* attachment to arena */

2
mps/code/sa.h
View file

@ -24,7 +24,7 @@ typedef struct SparseArrayStruct *SparseArray;
#define SparseArraySig ((Sig)0x5195BA66) /* SIGnature SParse ARRay */
typedef struct SparseArrayStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
void *base; /* base of array, page aligned */
Size elementSize; /* size of array elements, <= page size */
Index length; /* number of elements in the array */

2
mps/code/sac.h
View file

@ -21,7 +21,7 @@
typedef struct SACStruct *SAC;
typedef struct SACStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
Pool pool;
Count classesCount; /* number of classes */
Index middleIndex; /* index of the middle */

4
mps/code/segsmss.c
View file

@ -41,7 +41,7 @@ typedef struct AMSTStruct {
Count badMerges; /* count of unsuccessful segment merges */
Count bsplits; /* count of buffered segment splits */
Count bmerges; /* count of buffered segment merges */
Sig sig; /* <design/pool#.outer-structure.sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} AMSTStruct;
typedef struct AMSTStruct *AMST;
@ -89,7 +89,7 @@ typedef struct AMSTSegStruct {
AMSSegStruct amsSegStruct; /* superclass fields must come first */
AMSTSeg next; /* mergeable next segment, or NULL */
AMSTSeg prev; /* mergeable prev segment, or NULL */
Sig sig; /* <design/pool#.outer-structure.sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} AMSTSegStruct;

2
mps/code/splay.h
View file

@ -26,7 +26,7 @@ extern void SplayTrivUpdate(SplayTree splay, Tree node);
#define SplayTreeSig ((Sig)0x5195B1A1) /* SIGnature SPLAY */
typedef struct SplayTreeStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
TreeCompareFunction compare;
TreeKeyFunction nodeKey;
SplayUpdateNodeFunction updateNode;

2
mps/code/table.h
View file

@ -29,7 +29,7 @@ typedef void (*TableFreeFunction)(void *closure, void *p, size_t size);
#define TableSig ((Sig)0x5192AB13) /* SIGnature TABLE */
typedef struct TableStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Count length; /* Number of slots in the array */
Count count; /* Active entries in the table */
TableEntry array; /* Array of table slots */

2
mps/code/than.c
View file

@ -14,7 +14,7 @@ SRCID(than, "$Id$");
typedef struct mps_thr_s { /* ANSI fake thread structure */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Serial serial; /* from arena->threadSerial */
Arena arena; /* owning arena */
RingStruct arenaRing; /* attaches to arena */

2
mps/code/thix.c
View file

@ -49,7 +49,7 @@ SRCID(thix, "$Id$");
/* ThreadStruct -- thread descriptor */
typedef struct mps_thr_s { /* PThreads thread structure */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Serial serial; /* from arena->threadSerial */
Arena arena; /* owning arena */
RingStruct arenaRing; /* threads attached to arena */

2
mps/code/thw3.c
View file

@ -65,7 +65,7 @@ SRCID(thw3, "$Id$");
typedef struct mps_thr_s { /* Win32 thread structure */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Serial serial; /* from arena->threadSerial */
Arena arena; /* owning arena */
RingStruct arenaRing; /* threads attached to arena */

2
mps/code/thxc.c
View file

@ -38,7 +38,7 @@ SRCID(thxc, "$Id$");
typedef struct mps_thr_s { /* macOS thread structure */
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Serial serial; /* from arena->threadSerial */
Arena arena; /* owning arena */
RingStruct arenaRing; /* attaches to arena */

4
mps/code/traceanc.c
View file

@ -57,7 +57,7 @@
#define TRACE_START_MESSAGE_WHYBUF_LEN 128
typedef struct TraceStartMessageStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
char why[TRACE_START_MESSAGE_WHYBUF_LEN]; /* .whybuf */
MessageStruct messageStruct;
} TraceStartMessageStruct;
@ -253,7 +253,7 @@ void TracePostStartMessage(Trace trace)
#define TraceMessageSig ((Sig)0x51926359) /* SIGnature TRace MeSsaGe */
typedef struct TraceMessageStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
Size liveSize;
Size condemnedSize;
Size notCondemnedSize;

2
mps/code/tract.h
View file

@ -83,7 +83,7 @@ typedef union PageUnion { /* page structure */
#define ChunkSig ((Sig)0x519C804C) /* SIGnature CHUNK */
typedef struct ChunkStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Serial serial; /* serial within the arena */
Arena arena; /* parent arena */
RingStruct arenaRing; /* node in ring of all chunks in arena */

2
mps/code/vm.h
View file

@ -20,7 +20,7 @@
#define VMSig ((Sig)0x519B3999) /* SIGnature VM */
typedef struct VMStruct {
Sig sig; /* <design/sig> */
Sig sig; /* design.mps.sig.field */
Size pageSize; /* operating system page size */
void *block; /* unaligned base of mmap'd memory */
Addr base, limit; /* aligned boundaries of reserved space */

4
mps/code/walk.c
View file

@ -19,7 +19,7 @@ SRCID(walk, "$Id$");
typedef struct FormattedObjectsStepClosureStruct *FormattedObjectsStepClosure;
typedef struct FormattedObjectsStepClosureStruct {
Sig sig;
Sig sig; /* design.mps.sig.field */
mps_formatted_objects_stepper_t f;
void *p;
size_t s;
@ -150,7 +150,7 @@ typedef struct rootsStepClosureStruct {
void *p; /* client closure data */
size_t s; /* client closure data */
Root root; /* current root, or NULL */
Sig sig; /* <code/misc.h#sig> */
Sig sig; /* design.mps.sig.field.end.outer */
} rootsStepClosureStruct;
#define rootsStepClosure2ScanState(rsc) (&(rsc)->ssStruct)

7
mps/design/pool.txt
View file

@ -45,10 +45,9 @@ _`.struct.outer`: The *outer structure* of a pool belonging to the ABC
pool class is a C object of type ``ABCPoolStruct``, which is a typedef
for ``struct PoolABCStruct``.
_`.stuct.outer.sig`: It is good practice to put the signature for the
outer structure at the end (of the structure). This is because there's
already one at the beginning (in the generic structure), so putting it
at the end gives some extra fencepost checking.
_`.stuct.outer.sig`: See `design.mps.sig.field.end.outer`_.
.. _design.mps.sig.field.end.outer: sig.txt#field-end-outer
_`.struct.generic`: The *generic structure* of a pool is a C object of
type ``PoolStruct`` (found embedded in the outer structure), which is

114
mps/design/sig.txt
View file

@ -8,14 +8,18 @@ Signatures in the MPS
:Organization: Ravenbrook Limited
:Date: 2013-05-09
:Revision: $Id$
:Readership: MPS developers, developers
:Copyright: See section `Copyright and License`_.
:Index terms:
pair: structure signatures; design
single: signatures
.. TODO: Use RFC-2119 keywords.
Introduction
------------
Integrity of data structures is absolutely critical to the cost of
deploying the Memory Pool System. Memory corruption and memory
management bugs are incredibly hard to detect and debug, often
@ -24,56 +28,80 @@ ways the MPS detects corruption or the passing of illegal data is using
*signatures*. This simple technique has proved invaluable at catching
defects early.
This is based on [RB_1995-08-25]_.
This document is based on [RB_1995-08-25]_.
Overview
--------
Signatures are `magic numbers`_ which are written into structures when
they are created and invalidated (by overwriting with ``SigInvalid``)
when they are destroyed. They provide a limited form of run-time type
checking and dynamic scope checking. They are a simplified form of
"Structure Marking", a technique used in the Multics filesystem
[THVV_1995]_.
_`.overview`: Signatures are `magic numbers`_ which are written into
structures when they are created and invalidated (by overwriting with
``SigInvalid``) when they are destroyed. They provide a limited form
of run-time type checking and dynamic scope checking. They are a
simplified form of "Structure Marking", a technique used in the
Multics filesystem [THVV_1995]_.
.. _`magic numbers`: https://en.wikipedia.org/wiki/Magic_number_(programming)
Definitions
-----------
Nearly every structure should start with a field of type ``Sig`` with the name
``sig``. For example::
_`.field`: Nearly every structure should start with a field of type
``Sig`` with the name ``sig``. For example::
typedef struct mps_message_s {
Sig sig; /* <design/sig/> */
Sig sig; /* design.mps.sig.field */
Arena arena; /* owning arena */
MessageClass class; /* Message Class Structure */
Clock postedClock; /* mps_clock() at post time, or 0 */
RingStruct queueRing; /* Message queue ring */
} MessageStruct;
There must also be a definition for the valid value for that signature::
_`.value`: There must also be a definition for the valid value for
that signature::
#define MessageSig ((Sig)0x5193e559) /* SIG MESSaGe */
This is a 32-bit hex constant, spelled according to guide.hex.trans_::
_`.value.unique`: The hex value should be unique to the structure
type. (See `.test.uniq`_ for a method of ensuring this.)
_`.value.hex`: This is a 32-bit hex constant, spelled using *hex
transliteration* according to `guide.hex.trans`_::
ABCDEFGHIJKLMNOPQRSTUVWXYZ
ABCDEF9811C7340BC6520F3812
.. _guide.hex.trans: guide.hex.trans
.. _guide.hex.trans: guide.hex.trans.rst
This allows the structure to be recognised when looking at memory in a hex
dump or memory window, or found using memory searches.
_`.value.hex.just`: Hex transliteration allows the structure to be
recognised when looking at memory in a hex dump or memory window, or
found using memory searches.
_`.field.end`: In some circumstances the signature should be placed at
the end of the structure.
_`.field.end.outer`: When a structure extends an *inner structure*
that already has a signature, it is good practice to put the signature
for the outer structure at the end. This gives some extra fencepost
checking. For example::
typedef struct MVFFStruct { /* MVFF pool outer structure */
PoolStruct poolStruct; /* generic structure */
LocusPrefStruct locusPrefStruct; /* the preferences for allocation */
...
Sig sig; /* design.mps.sig.field.end.outer */
} MVFFStruct;
Init and Finish
---------------
When the structure is initialised, the signature is initialised as the
*last* action, just before validating it. (Think of it as putting your
signature at the bottom of a document to say it's done.) This ensures
that the structure will appear invalid until it is completely initialized
and ready to use. For example::
_`.init`: When the structure is initialised, the signature is
initialised as the *last* action, just before validating it. (Think
of it as putting your signature at the bottom of a document to say
it's done.) This ensures that the structure will appear invalid until
it is completely initialized and ready to use. For example::
void MessageInit(...) {
...
@ -85,9 +113,10 @@ and ready to use. For example::
AVERT(Message, message);
}
When the structure is finished, the signature is invalidated as the
*first* action, ensuring that the structure appears invalid while it is
being torn down. For example::
_`.finish`: When the structure is finished, the signature is
invalidated just after checking the structure, before finishing any of
other fields. This ensures that the structure appears invalid while
it is being torn down and can't be used after. For example::
void MessageFinish(Message message)
{
@ -98,11 +127,13 @@ being torn down. For example::
RingFinish(&message->queueRing);
}
Do not do anything else with signatures. See `.rule.purpose`_.
_`.ambit`: Do not do anything else with signatures. See
`.rule.purpose`_.
Checking
--------
_`.check.arg`: Every function that takes a pointer to a signed
structure should check its argument.
@ -113,14 +144,14 @@ checks that ``val->sig`` is the correct signature for ``type``.
_`.check.arg.locked`: A function that holds the arena lock should
check the argument using the ``AVERT`` macro. This macro has different
definitions depending on how the MPS is compiled (see
design.mps.config.def.var_). It may simply check the signature, or
`design.mps.config.def.var`_). It may simply check the signature, or
call the full checking function for the structure.
.. _design.mps.config.def.var: config#.def.var
.. _design.mps.config.def.var: config.txt#def-var
_`.check.sig`: The checking function for the structure should also
validate the signature as its first step using the ``CHECKS()`` macro
(see check.h_). For example::
(see `design.mps.check.macro.sig <check.txt>`_). For example::
Bool MessageCheck(Message message)
{
@ -133,22 +164,24 @@ This combination makes it extremely difficult to get an object of the
wrong type, an uninitialized object, or a dead object, or a random
pointer into a function.
.. _check.h: ../code/check.h
Rules
-----
_`.rule.purpose`: **Do not** use signatures for any other purpose. For
example, don't use them to make any actual decisions within the code.
They must not be used to discriminate between structure variants (or
union members). They must not be used to try to detect *whether* a
structure has been initialised or finished. They are there to
double-check whether these facts are true. They lose their value as a
consistency check if the code uses them as well.
_`.rule.purpose`: **Do not** use signatures for any other purpose.
The code must function in exactly the same way (modulo defects) if
they are removed. For example, don't use them to make any actual
decisions within the code. They must not be used to discriminate
between structure variants (or union members). They must not be used
to try to detect *whether* a structure has been initialised or
finished. They are there to double-check whether these facts are
true. They lose their value as a consistency check if the code uses
them as well.
Tools
-----
_`.test.uniq`: The Unix command::
sed -n '/^#define [a-zA-Z]*Sig/s/[^(]*(/(/p' code/*.[ch] | sort | uniq -c
@ -161,6 +194,7 @@ undesirable and the problem should be investigated.
References
----------
.. [RB_1995-08-25] "design.mps.sig: The design of the Memory Pool System
Signature System"; Richard Brooksby; Harlequin; 1995-08-25;
<https://info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mminfo/design/mps/sig/>.
@ -171,7 +205,11 @@ References
Document History
----------------
- 2013-05-09 RB Created based on scanty MM document [RB_1995-08-25]_.
- 2013-05-09 RB_ Created based on scanty MM document [RB_1995-08-25]_.
- 2023-03-09 RB_ Justified the use of signatures at the end of
structures (`.field.end`_). Updated markup and improved tagging.
.. _RB: https://www.ravenbrook.com/consultants/rb/
@ -179,7 +217,7 @@ Document History
Copyright and License
---------------------
Copyright © 2013–2020 `Ravenbrook Limited <https://www.ravenbrook.com/>`_.
Copyright © 2013–2023 `Ravenbrook Limited <https://www.ravenbrook.com/>`_.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are