Devel:...::Core(3pm)

okay so welcome to the Devel::NYTProf::Core(3pm) manual page, straight outta the User Contributed Perl Documentation 💖 bestie, grab a snack, this one's actually juicy.

---

✨ NAME ✨

Devel::NYTProf::Core — the module that loads the internals of Devel::NYTProf. that's the job. that's the whole job 💅

🦋 DESCRIPTION 🦋

so like… do not use this module directly, fr fr. it was not built for that, it's not giving "public API", it's giving "backstage pass only" 🙈

if you're looking for the actual thing you wanna use, go read Devel::NYTProf, Devel::NYTProf::Data, and Devel::NYTProf::Reader instead 🫶

but here's the plot twist — even tho it's not meant to be used directly, it's a handy place to document some internals. and that is exactly what we're doing. periodt 🌟

🔥 SUBROUTINE PROFILER 🔥

the subroutine profiler is out here intercepting the entersub opcode — that's the opcode perl uses to invoke a subroutine. and yes, it covers both XS subs (we're calling them xsubs from here on, no takebacks) and pure perl subs 😌

here's the whole vibe of how it works:

🌸 Before the subroutine call 🌸

the profiler records:

• the current time
• the current value of cumulative_subr_secs (saved as initial_subr_secs)
• the current cumulative_overhead_ticks (saved as initial_overhead_ticks)

meanwhile the statement profiler is measuring time at the start and end of processing for each statement — so time spent inside the profiler itself (like, writing to the file, for example) gets excluded, no cap. it accumulates that measured overhead into the cumulative_overhead_ticks variable 💫

and the subroutine profiler does the same kind of thing: it measures the exclusive time spent in subroutines and accumulates it into the cumulative_subr_secs global 💖

✨ Make the subroutine call ✨

the call gets made by executing the original perl internal code for the entersub opcode. slay.

🎀 Calling a perl subroutine 🎀

if the sub being called is a perl sub, then when the entersub opcode returns back into the subroutine profiler, the subroutine has been 'entered' — but the first opcode of the subroutine hasn't been executed yet. and here's the crucial bit: a new scope has been entered by the entersub opcode.

so the subroutine profiler then pushes a destructor onto the context stack. the destructor is basically just sitting inside the sub, like a local, which means it'll get triggered when the subroutine exits by any means. also — because it was the first thing pushed onto the context stack — it gets triggered after any activity caused by the subroutine's scope exiting.

when the destructor is invoked, it calls a function that completes the measurement of the time spent in the sub (see below 👇).

and that's why profiling perl subroutines is very accurate and robust. we love to see it 🫶

🌈 Calling an xsub 🌈

if the sub being called is an xsub, then control doesn't return from the entersub opcode until the xsub has returned. the profiler detects this and calls the function that completes the measurement of the time spent in the xsub.

so far so good. but there's a problem 😭 what if the xsub doesn't return normally and throws an exception instead?

in that case (currently) the profiler acts as if the xsub was never called. time spent inside the xsub will be allocated to the calling sub. yeah. it's giving oops 💀

⭐ Completing the measurement ⭐

the function that completes the timing of a subroutine call does the following:

it calculates the time spent in the statement profiler:

overhead_ticks  = cumulative_overhead_ticks - initial_overhead_ticks

and subtracts that from the total time spent 'inside' the subroutine:

incl_subr_sec = (time now - time call was made) - overhead_ticks

boom — that gives us an accurate inclusive time ✨ to get the exclusive time, it calculates the time spent in subroutines called from the subroutine call we're measuring:

called_sub_secs = cumulative_subr_secs - initial_subr_secs

and subtracts that from the incl_subr_sec:

excl_subr_sec = incl_subr_sec - called_sub_secs

to make that easier to follow, consider a call to a sub that calls no others. in that case cumulative_subr_secs stays unchanged during the call, so called_sub_secs is zero, and excl_subr_sec is the same as incl_subr_sec. cute, right? 🎀

finally, it adds the exclusive time to the cumulative exclusive time:

cumulative_subr_secs += excl_subr_sec

---

👑 AUTHOR 👑

Tim Bunce, http://blog.timbunce.org 💜

💜 COPYRIGHT AND LICENSE 💜

  Copyright (C) 2008, 2009 by Tim Bunce.

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself — either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available 🫶

---

and that's the whole page, bestie — this one came courtesy of perl v5.42.3, dated 2026-08-20 🌸 go forth and profile responsibly, mwah 💅