diff --git a/mps/code/trace.c b/mps/code/trace.c index 9507eb8f726..0a3d95f4517 100644 --- a/mps/code/trace.c +++ b/mps/code/trace.c @@ -1,11 +1,12 @@ /* trace.c: GENERIC TRACER IMPLEMENTATION * * $Id$ - * Copyright (c) 2001-2020 Ravenbrook Limited. + * Copyright (c) 2001-2023 Ravenbrook Limited. * See end of file for license. * Portions copyright (C) 2002 Global Graphics Software. * - * .design: . */ + * .design: design.mps.trace. + */ #include "locus.h" #include "mpm.h" @@ -81,10 +82,10 @@ void ScanStateInit(ScanState ss, TraceSet ts, Arena arena, AVERT(Rank, rank); /* white is arbitrary and can't be checked */ - /* NOTE: We can only currently support scanning for a set of traces - with the same fix method. To remove this restriction, it would be - necessary to dispatch to the fix methods of sets of traces in - TraceFix. */ + /* .fix.single: NOTE: We can only currently support scanning for a + set of traces with the same fix method. To remove this + restriction, it would be necessary to dispatch to the fix methods + of sets of traces in TraceFix. See also impl.c.trans.park. */ ss->fix = NULL; ss->fixClosure = NULL; TRACE_SET_ITER(ti, trace, ts, arena) { @@ -1920,7 +1921,7 @@ Res TraceDescribe(Trace trace, mps_lib_FILE *stream, Count depth) /* C. COPYRIGHT AND LICENSE * - * Copyright (C) 2001-2020 Ravenbrook Limited . + * Copyright (C) 2001-2023 Ravenbrook Limited . * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are diff --git a/mps/code/trans.c b/mps/code/trans.c index a19d877c125..62846ff9f61 100644 --- a/mps/code/trans.c +++ b/mps/code/trans.c @@ -1,30 +1,14 @@ /* trans.c: TRANSFORMS IMPLEMENTATION * * $Id$ - * Copyright 2011-2022 Ravenbrook Limited. See end of file for license. + * Copyright 2011-2023 Ravenbrook Limited. See end of file for license. * - * A transform is a special kind of garbage collection that replaces references - * to a set of objects. The transform is piggybacked onto a garbage - * collection by overriding the fix method for a trace. The mapping used to - * replace the references is built up in a hash table by the client. - * - * - * Rationale - * - * This design was arrived at after some pain. The MPS isn't really designed - * for this kind of thing, and the pools generally assume that they're doing - * a garbage collection when they're asked to condemn, scan, fix, and reclaim - * stuff. This makes it very hard to apply the transform without also doing - * a garbage collection. Changing this would require a significant reworking - * of the MPS to generalise its ideas, and would bloat the pool classes. - * - * - * Assumptions: - * - * - Single-threaded mutator. In fact this code might work if other mutator - * threads are running, since the shield ought to operate correctly. - * However, in this case there can only be one trace running so that the - * correct fix method is chosen by ScanStateInit. + * A transform is a special kind of garbage collection that replaces + * references to a set of objects. The transform is piggybacked onto + * a garbage collection by overriding the fix method for a trace + * (design.mps.trace.fix). The mapping used to replace the references + * is built up in a hash table by the client. See + * design.mps.transform. */ #include "trans.h" @@ -297,6 +281,10 @@ Res TransformApply(Bool *appliedReturn, Transform transform) globals = ArenaGlobals(arena); AVERT(Globals, globals); + /* .park: Parking the arena ensures that there is a trace available + and that no other traces are running, so that the tracer will + dispatch to transformFix correctly. See + impl.c.trace.fix.single. */ ArenaPark(globals); res = TraceCreate(&trace, arena, TraceStartWhyEXTENSION); @@ -349,7 +337,7 @@ done: /* C. COPYRIGHT AND LICENSE * - * Copyright (C) 2011-2022 Ravenbrook Limited . + * Copyright (C) 2011-2023 Ravenbrook Limited . * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are diff --git a/mps/design/transform.txt b/mps/design/transform.txt index 503e8b5cd0f..d060152f17f 100644 --- a/mps/design/transform.txt +++ b/mps/design/transform.txt @@ -68,6 +68,14 @@ collection trace in which the fix function is substituted by "new" ones, in addition to applying the usual garbage collection fix function. +This design was arrived at after some pain. The MPS isn't really +designed for generalized transformation of the object graph, and the +pools generally assume that they're doing a garbage collection when +they're asked to condemn, scan, fix, and reclaim stuff. This makes it +very hard to apply the transform without also doing a garbage +collection. Changing this would require a significant reworking of +the MPS to generalise its ideas, and would bloat the pool classes. + Not yet written --------------- @@ -86,8 +94,7 @@ Not yet written * Nice side-effect is that "old" objects are killed. -* Why the arena must be parked. - +* Why the arena must be parked (see impl.c.trans.park). References @@ -116,6 +123,9 @@ Document History - 2022-01-23 GDR_ Converted to reStructuredText. +- 2023-06-16 RB_ Updated and improved in order to make Transforms part + of the public MPS. + .. _RB: https://www.ravenbrook.com/consultants/rb/ .. _GDR: https://www.ravenbrook.com/consultants/gdr/ @@ -123,7 +133,7 @@ Document History Copyright and License --------------------- -Copyright © 2012–2020 `Ravenbrook Limited `_. +Copyright © 2012–2023 `Ravenbrook Limited `_. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are