Skip to content

Faster PHP callbacks with a struct

Callbacks are everywhere in PHP: array_filter, usort, XML parser handlers, session handlers, WordPress hooks, closures passed around in every modern framework. On .NET, those calls go through the PeachPie runtime's IPhpCallable.Invoke. Thanks to a great contribution from @arontsang, that hot path just got leaner. Let's take a look at what changed and why it matters.

Intro

Pull request #1170 - Using a struct to marshal data into PhpCallable.Invoke for performance has just been merged into master. It's a small change in terms of the idea, but it touches one of the most frequently executed pieces of code in the runtime: the way arguments are handed over to a PHP callable.

The best part? It's completely transparent. No public API changes, no changes to your PHP code, and no changes to how you call PHP callables from C#.

How PHP callables are invoked

Every PHP callable in PeachPie (a function name, a closure, an [$obj, 'method'] array, an object with __invoke) ends up behind the IPhpCallable interface. At its core, the interface takes the arguments as a span:

public partial interface IPhpCallable
{
    PhpValue Invoke(Context ctx, params ReadOnlySpan<PhpValue> arguments);
    PhpValue Invoke(Context ctx, params PhpValue[] arguments);
}

To make life easy for the library code (and for you in C#), the runtime also provides convenience overloads with fixed arity: Invoke(ctx, p0), Invoke(ctx, p0, p1), all the way up to 16 arguments. These are generated from a T4 template (PhpCallable.ArrayPool.tt). The runtime libraries use them all over the place. For example, the XML parser calls your element handler like this:

StartElementHandler.Invoke(_ctx, PhpValue.FromClass(this), (PhpValue)elementName, (PhpValue)attributeArray);

usort() calls your comparison function with two values (_compare.Invoke(_ctx, x, y)) for every comparison it makes while sorting, and array_filter() with ARRAY_FILTER_USE_BOTH calls your callback with the value and the key for every single element of the array.

The problem

The fixed-arity overloads need to turn their individual parameters into a ReadOnlySpan<PhpValue>. Until now, the 2- to 16-argument overloads did that by renting a temporary array from the shared ArrayPool:

sealed PhpValue Invoke(Context ctx, PhpValue p0, PhpValue p1)
{
    var phpArgs = ArrayPool<PhpValue>.Shared.Rent(2);
    try
    {
        phpArgs[0] = p0;
        phpArgs[1] = p1;
        return Invoke(ctx, new ReadOnlySpan<PhpValue>(phpArgs, 0, 2));
    }
    finally
    {
        ArrayPool<PhpValue>.Shared.Return(phpArgs, true);
    }
}

ArrayPool is already a lot better than new PhpValue[2] on every call, but it isn't free:

  • every call does a rent and a return on the shared pool,
  • the pool hands out arrays from its smallest bucket, which is bigger than the two or three arguments we actually need, and Return(..., true) clears the whole array every time,
  • when the pool has nothing ready (e.g. on a fresh thread), it falls back to allocating a new array on the heap,
  • and there's a try/finally around every callback invocation.

For a callback that runs once, none of this matters. For a comparison function called by usort on a big array, or a handler invoked for every node of an XML document, it adds up.

The struct trick

The single-argument overload never had this problem. It simply creates a span over its own parameter:

sealed PhpValue Invoke(Context ctx, PhpValue p0) => Invoke(ctx, MemoryMarshal.CreateReadOnlySpan(ref p0, 1));

Aron's PR takes the same idea and applies it to all the other arities. The template now generates a small, private, sequentially laid out struct for each arity from 2 to 16:

[StructLayout(LayoutKind.Sequential)]
private struct PhpArgTuple2
{
    public PhpValue Argument0;
    public PhpValue Argument1;
}

The arguments are copied into the struct, which lives on the stack, and a ReadOnlySpan<PhpValue> is created directly over its fields:

sealed PhpValue Invoke(Context ctx, PhpValue p0, PhpValue p1)
{
    var tuple = new PhpArgTuple2
    {
        Argument0 = p0,
        Argument1 = p1,
    };
    var phpArgs = MemoryMarshal.CreateReadOnlySpan(ref tuple.Argument0, 2);
    return Invoke(ctx, phpArgs);
}

Because the struct is LayoutKind.Sequential and contains nothing but PhpValue fields, they sit next to each other in memory exactly like the elements of an array. The span sees them as one.

Why is it faster?

  • No pool round-trip. There is no Rent or Return on the shared pool, and no clearing of a rented array afterwards.
  • No heap allocation, ever. The arguments live on the stack, so even the case where the pool would have had to allocate a new array is gone. Less work for the garbage collector, which is exactly the kind of improvement we like (remember the string allocation work in 1.1.10?).
  • No try/finally. The method body is now three straight lines, which is friendlier to the JIT.
  • Better locality. The arguments are right there on the current stack frame, next to the rest of the call.

PhpValue itself is a small readonly struct (a type code, a value field, and an object reference), so even the 16-argument tuple is just a few hundred bytes of stack. That's perfectly fine for a single call frame.

The PR doesn't include benchmark numbers, so we won't make any up! The effect is fewer allocations and less overhead per callback call, and it's most noticeable in callback-heavy code: sorting with user comparators, array_filter/array_map over large arrays, XML parsing with handlers, and frameworks that dispatch lots of hooks and events. If you measure it on your own app, we'd love to see the numbers. Drop them in the PR or on our Discord. The repository also has a src/Tests/Benchmarks project, if you feel like contributing a proper benchmark. 😉

Correctness

Nothing changes semantically. The IPhpCallable.Invoke signatures are exactly the same, the new PhpArgTuple* structs are private, and every overload still ends up in the same Invoke(Context, ReadOnlySpan<PhpValue>) core. Static functions, instance methods, closures, array callables, and string function names all go through the same path as before. The test suite produced the same results before and after the change.

How to try it

The change is merged into master and will ship with the next PeachPie release. It isn't part of the current 1.1.13 packages on NuGet yet.

If you can't wait, build PeachPie from sources:

git clone https://github.com/peachpiecompiler/peachpie.git
cd peachpie
dotnet build

The build puts the NuGet packages into the .nugs folder with the 1.2.0-dev version. Run build/update-cache.ps1 to copy them into your local NuGet cache, and reference them from your project:

<Project Sdk="Peachpie.NET.Sdk/1.2.0-dev">

See Building PeachPie for more details. Our Patreon members also get access to nightly builds.

Thank you, Aron!

A big shoutout to @arontsang for this contribution, and for your patience while the PR waited for us. 🙏 This is exactly the kind of thing that makes PeachPie better for everyone: a precise and well-scoped change to a hot path that every PHP app on .NET benefits from, without anyone having to change a line of code.

Have an idea for how to make PeachPie faster? Check out the repository, open an issue or a pull request, or come chat with us on Discord. We'd love to have you on board!