|
| 1 | +# Anonymous subroutine naming via `*__ANON__` |
| 2 | + |
| 3 | +## Problem |
| 4 | + |
| 5 | +`local *__ANON__ = 'name'` is a Perl idiom for giving an anonymous |
| 6 | +subroutine a temporary name visible to `caller()`, `Carp`, and |
| 7 | +`Sub::Util::subname()`. It is used by `SUPER.pm`, `Try::Tiny`, |
| 8 | +`namespace::clean`, and several Moose internals to make stack traces |
| 9 | +and SUPER-dispatch work correctly when subs are installed under |
| 10 | +unusual names (or not installed at all). |
| 11 | + |
| 12 | +In PerlOnJava the idiom is silently lost: |
| 13 | + |
| 14 | +```perl |
| 15 | +my $s = sub { local *__ANON__ = 'myname'; (caller(0))[3] }; |
| 16 | +$s->(); |
| 17 | +# real perl: main::myname |
| 18 | +# jperl: main::__ANON__ |
| 19 | +``` |
| 20 | + |
| 21 | +The root cause: `caller()` and `Sub::Util::subname` read the cached |
| 22 | +`RuntimeCode.subName`, which for anonymous subs is always `null` (and |
| 23 | +falls back to `"__ANON__"`). Real perl resolves the name dynamically |
| 24 | +through `CvGV(cv)->NAME`, so a `local`-scoped alias of the package's |
| 25 | +`*__ANON__` glob is observed as a rename. |
| 26 | + |
| 27 | +This blocks `SUPER` (3 of 6 tests fail in `t/bugs.t`), which in turn |
| 28 | +blocks `Test::MockModule`, which in turn blocks `DBIx::Retry` and |
| 29 | +others. |
| 30 | + |
| 31 | +## Goal |
| 32 | + |
| 33 | +Make `caller()` and `Sub::Util::subname` honor `local *PKG::__ANON__ |
| 34 | += 'name'` for the dynamic scope of the local, without regressing |
| 35 | +existing behavior or `Sub::Name`/`Sub::Util::set_subname`. |
| 36 | + |
| 37 | +## Design — pragmatic glob indirection (Option A) |
| 38 | + |
| 39 | +### Data model |
| 40 | + |
| 41 | +1. `RuntimeGlob` gains an optional field |
| 42 | + ```java |
| 43 | + public String nameOverride; // null by default |
| 44 | + ``` |
| 45 | + This represents the dynamic "name override" of the glob — i.e. the |
| 46 | + string most recently assigned via `*foo = $string`. |
| 47 | + |
| 48 | +2. `RuntimeCode` does **not** need a new field. Anonymous subs |
| 49 | + already carry `packageName` (the CvSTASH equivalent), and that's |
| 50 | + enough to locate the relevant `*PKG::__ANON__` glob via |
| 51 | + `GlobalVariable.globalIORefs.get(packageName + "::__ANON__")`. |
| 52 | + |
| 53 | +### Write path: `*PKG::FOO = $string` |
| 54 | + |
| 55 | +In `RuntimeGlob.set(RuntimeScalar value)`, the scalar-value cases |
| 56 | +(STRING / BYTE_STRING / INTEGER / DOUBLE / BOOLEAN / VSTRING / |
| 57 | +DUALVAR) currently store `value` into the SCALAR slot. We add: |
| 58 | + |
| 59 | +```java |
| 60 | +RuntimeGlob current = GlobalVariable.globalIORefs.getOrDefault( |
| 61 | + this.globName, this); |
| 62 | +current.nameOverride = value.toString(); |
| 63 | +``` |
| 64 | + |
| 65 | +We update `current` rather than `this` because `local *FOO` swaps in |
| 66 | +a new RuntimeGlob in `globalIORefs`; the lvalue captured before |
| 67 | +`local` still references the old RuntimeGlob, but the override must |
| 68 | +be visible to readers that look up the *current* glob by name. The |
| 69 | +existing SCALAR-slot write already follows this "look up by name" |
| 70 | +pattern (see `getGlobalVariable(this.globName)` in `set(STRING)`). |
| 71 | + |
| 72 | +The override is **only** set by glob-as-scalar assignment; plain |
| 73 | +`$PKG::__ANON__ = $x` continues to write the SCALAR slot without |
| 74 | +touching `nameOverride`. This matches real Perl's distinction |
| 75 | +between glob assignment (which does the stash-alias trick) and |
| 76 | +scalar assignment. |
| 77 | + |
| 78 | +### Local-scope handling |
| 79 | + |
| 80 | +`RuntimeGlob.dynamicSaveState()` already creates a fresh |
| 81 | +`RuntimeGlob` for the local scope and installs it in `globalIORefs`. |
| 82 | +A fresh glob has `nameOverride == null`, so the local scope starts |
| 83 | +clean. `dynamicRestoreState()` restores the original glob, whose |
| 84 | +`nameOverride` was never mutated, so no extra save/restore is |
| 85 | +needed. |
| 86 | + |
| 87 | +### Read path: `caller()` and `Sub::Util::subname` |
| 88 | + |
| 89 | +For anonymous subs (where `code.subName` is null/empty and |
| 90 | +`code.explicitlyRenamed` is false), consult the override: |
| 91 | + |
| 92 | +```java |
| 93 | +String name = null; |
| 94 | +if (!code.explicitlyRenamed |
| 95 | + && (code.subName == null || code.subName.isEmpty()) |
| 96 | + && code.packageName != null) { |
| 97 | + RuntimeGlob anonGlob = GlobalVariable.globalIORefs.get( |
| 98 | + code.packageName + "::__ANON__"); |
| 99 | + if (anonGlob != null && anonGlob.nameOverride != null |
| 100 | + && !anonGlob.nameOverride.isEmpty()) { |
| 101 | + name = code.packageName + "::" + anonGlob.nameOverride; |
| 102 | + } |
| 103 | +} |
| 104 | +if (name == null) { |
| 105 | + // existing fallback: "Pkg::__ANON__" or stack-trace info |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +Lookup order: |
| 110 | + |
| 111 | +1. `code.explicitlyRenamed` (`Sub::Name`, `Sub::Util::set_subname`) |
| 112 | + wins outright — this matches real Perl, where a CV whose `CvGV` |
| 113 | + has been repointed by `Sub::Name` is no longer affected by |
| 114 | + `local *__ANON__` higher up. |
| 115 | +2. Anonymous-sub override via `*PKG::__ANON__`'s `nameOverride`. |
| 116 | +3. Fallback: `Pkg::__ANON__` (current behavior). |
| 117 | + |
| 118 | +### Interaction with `Sub::Name` / `Sub::Util::set_subname` |
| 119 | + |
| 120 | +`Sub::Name::subname` and `Sub::Util::set_subname` mutate |
| 121 | +`RuntimeCode.subName`/`packageName` and set |
| 122 | +`explicitlyRenamed = true`. The new lookup explicitly checks |
| 123 | +`explicitlyRenamed` first, so: |
| 124 | + |
| 125 | +- Sub::Name on a sub that's also under `local *__ANON__`: the |
| 126 | + Sub::Name name wins (matches real perl). |
| 127 | +- Plain anon sub under `local *__ANON__`: the override wins. |
| 128 | +- Plain anon sub outside any local: falls back to |
| 129 | + `Pkg::__ANON__` as today. |
| 130 | + |
| 131 | +`B::CV->GV->NAME` and the `_is_renamed` shim in `Sub::Name` are not |
| 132 | +touched in this change. A future cleanup could fold the |
| 133 | +`explicitlyRenamed` mechanism into the same glob-indirection model |
| 134 | +(repointing the anon-glob link on `set_subname`), letting us delete |
| 135 | +`_is_renamed`. That's left for follow-up. |
| 136 | + |
| 137 | +## Tests |
| 138 | + |
| 139 | +### Regression baseline (must keep passing) |
| 140 | + |
| 141 | +Captured in `dev/modules/anon_sub_naming_baseline.txt`. Highlights: |
| 142 | + |
| 143 | +| Idiom | Expected name | |
| 144 | +|----------------------------------------|------------------| |
| 145 | +| `Sub::Name::subname('My::r', $s)` | `My::r` | |
| 146 | +| `Sub::Util::set_subname('O::n', $s)` | `O::n` | |
| 147 | +| Plain `sub { ... }` in `main` | `main::__ANON__` | |
| 148 | +| Plain `sub { ... }` in `Foo::Bar` | `Foo::Bar::__ANON__` | |
| 149 | +| `B::svref_2object(set_subname'd)->GV->NAME` | `n` | |
| 150 | + |
| 151 | +### New behavior (must start passing) |
| 152 | + |
| 153 | +| Idiom | Expected name | |
| 154 | +|------------------------------------------------|---------------| |
| 155 | +| `local *__ANON__ = 'myname'` in `sub { caller }` | `main::myname` | |
| 156 | +| `local *Foo::__ANON__ = 'x'` in `Foo` package | `Foo::x` | |
| 157 | +| Sub::Name'd sub also under `local *__ANON__` | Sub::Name's name (unchanged) | |
| 158 | +| Carp longmess from sub under `local *__ANON__` | reflects override | |
| 159 | +| SUPER.pm `t/bugs.t` | 6/6 pass | |
| 160 | + |
| 161 | +### End-to-end |
| 162 | + |
| 163 | +`./jcpan -i SUPER` should pass tests; `./jcpan -i Test::MockModule` |
| 164 | +should follow; `./jcpan -t DBIx::Retry` should at least get past |
| 165 | +the "Test::MockModule not found" stage. |
| 166 | + |
| 167 | +## Out of scope |
| 168 | + |
| 169 | +- Making `*foo = "string"` do the full Perl stash-alias dance for |
| 170 | + arbitrary glob names. We only honor the override for naming |
| 171 | + purposes; the SCALAR slot semantics of glob-string assignment are |
| 172 | + unchanged. |
| 173 | +- Rebuilding `Sub::Name` on top of glob indirection. |
| 174 | +- `B::CV->GV->NAME` reflecting the override dynamically (currently |
| 175 | + always reports `__ANON__` for anon subs; not consulted by SUPER). |
| 176 | + |
| 177 | +## Status |
| 178 | + |
| 179 | +- [x] Design |
| 180 | +- [x] Baseline captured (`anon_sub_naming_baseline.txt`) |
| 181 | +- [x] Implementation |
| 182 | + - `RuntimeGlob.nameOverride` field |
| 183 | + - `RuntimeGlob.set(scalar)` records override on the live glob via |
| 184 | + `peekGlobalIO(globName)` |
| 185 | + - `GlobalVariable.peekGlobalIO(name)` non-vivifying lookup |
| 186 | + - `RuntimeCode.callerWithSub` consults override for both |
| 187 | + innermost (via `currentSub`) and deeper (via stack-trace |
| 188 | + `Pkg::__ANON__` frame) anon frames |
| 189 | + - `SubUtil.subname` consults override |
| 190 | +- [x] SUPER `t/bugs.t` passes 6/6 |
| 191 | +- [x] `Test::MockModule` installs and tests pass 103/103 |
| 192 | +- [x] `DBIx::Retry` test chain unblocked (17 subtests run, 1 |
| 193 | + remaining unrelated DBD::ExampleP failure) |
| 194 | +- [x] Sub::Name baseline diff is empty (no regressions) |
| 195 | +- [x] `make` passes |
0 commit comments