Implement Managed vs. Manual Series Model

[hostilefork]

In the spirit of Comments vs Web Links on the World Wide Web, I thought it would be a good time to take out a longstanding note from Carl labeled "ideas" in m-pools.c and migrate it to a GitHub issue that I plan to be committing a fix for soon (hopefully).

It happens that he's describing something I did wind up realizing something had to be done about. He wrote:

Each task needs its own series-save list that is simply a pointer array of un-rooted (NEW) series that should not be GCed. When a TRAP or THROW occurs, the list is trimmed back to its prior marker, allowing series that were orphaned by the TRAP to be GCed.

When GC occurs, each series on the save list is mark-scanned to keep it alive. The save list can be expanded, but care should be used to avoid creating a huge list when recursion happens.

What if interpreter kept track of save list marker when calling each native, and reset it on return?

This is an extension of the current "GC Infants" idea, which saves the last few created series from being garbage collected. Picking the last N to protect doesn't make a lot of sense--however--and is more likely to cover up a bug and make difficult repro scenarios.

What I came up with was that series are considered to not be shown to the GC until they have been explicitly "shared" with it. This moves them from a manual memory state to a managed memory state. Rebol code is able to call Free_Series until the sharing has been done...but once the sharing happens, only the GC can free it and calls to Free_Series will assert.

These "infant" series (or "Triage", as I called them) are freed automatically when a Trap happens as Carl suggests...because the interpreter state capture holds the list. But if a trap does not happen, an assert at the end of the native notifies you of the leak in the debug build. In a release build, these would be permanent memory leaks. Each native also ensures the data stack is balanced...

[zsx]

I think what I have in this commit zsx/r3@4c91c1e can be used for this purpose.

For every new series:

REBSER *ser = Make_Series();
RL_Push_Aux(ser, Free_Series);

/* use the series */

/* done with the series */
RL_Pop_And_Free_Aux();

If you find it tedious to do a pop for each push, you can do:

REBCNT asp = RL_Get_Aux_Pointer();

REBSER *ser = Make_Series();
RL_Push_Aux(ser, Free_Series);

REBSER *ser2 = Make_Series();
RL_Push_Aux(ser2, Free_Series);

/* use the series */

/* done with all series */
RL_Restore_And_Free_Aux_Pointer(asp);

[hostilefork]

The mechanism I have is that there are three lists: Triage, Shared, and Kept.

When a series is first created, it carries the flag SER_MANUAL. A series with this flag may be freed with Free_Series by code that is not the garbage collector. (The GC has a special unexported hook, allowing it to free a series that does not have the SER_MANUAL flag.)

There is an operation called Share_Series which removes the SER_MANUAL flag. In debug builds, before a value is accepted as input to a Do_Next or given as a result from it, the values are checked that they have been shared and are not still SER_MANUAL. Hence, not having SER_MANUAL implies shared...and it is illegal to call Free_Series on them.

The SER_KEEP flag is independent, and can be added or removed to a series whether it is in a manual state or not. However, any series carrying this flag will not be garbage collected...and it is effectively a GC root so anything it refers to is not GC'd either.

When a Do_Next is run, it marks the point in the triage list it started with (all the SER_MANUAL series). If the operation traps, all the manual series will be freed. If it completes, there is an assertion in the debug build that there are no series outstanding.

The trickiest bit is managing the SER_MANUAL bit on a series in situations where series are deeply copied. The convention I adopted is that a copy will get the manual/shared status of its input...simply because it would be too costly to walk the series to flip the bit recursively when a share happens.

That's what I was basing things on. The mechanical requirement is to be able to pull a series out of the middle of the manual triage list; I used a doubly-linked list for Triage, Shared, and Kept... and would just move a series from one to the other. I used this same list for enumeration in the GC (I wasn't using memory pools). I'll have to think about how to graft it back in... your "always allocate" flag is a good trick in the pools. I will think on how to blend the approaches (now that I've decided the memory pools make sense, given that a series can expand to use a block larger than it requested).

[hostilefork]

This is all taken care of. The new language I used was "managed" series as opposed to "shared".