Gene's Blog

Starting processes in job objects with C#

2026-01-28T05:00:00.000Z

Raymond Chen wrote a helpful article explaining the safest method of starting a process directly in a job object on Windows 10 and above. (I say "safest", because it avoids a pesky race condition cleanly and effectively; but more on that later.) Working directly with the Windows API in C# is a different story. Nevertheless, it's something we must do when attempting to replicate Chen's logic.

Creating a job object

Permalink to “Creating a job object” #

It's recommended that modern .NET apps use CsWin32 for P/Invoke support, so that's what we'll do. At this point, our NativeMethods.txt only needs one entry:

CreateJobObject

And with this method, it becomes very simple to create job objects:

public static SafeFileHandle CreateJobHandle()
{
    var safeJobHandle = PInvoke.CreateJobObject(null, null);

    if (safeJobHandle.IsInvalid)
        // Error handling

    return safeJobHandle;
}

As an aside

Permalink to “As an aside” #

You'll notice I won't take up space writing any error handling in this article. As a general WinAPI rule, when a system function fails, it will usually return 0. To obtain the error code and create an exception, you can do something like:

if (!PInvoke.Win32Function())
{
    var errorCode = Marshal.GetLastPInvokeError();
    var win32Ex = new Win32Exception(errorCode);
    // Error handling
}

With that being said, let's move on to the main course... How can we start a process in our newly created job object?

The gotchas of the Process class

Permalink to “The gotchas of the Process class” #

Looking at Microsoft's documentation for .NET's Process class, we see many useful members. We can use a StartInfo object to set characteristics of the process before starting it. We can even access the underlying OS handle with Process.Handle.

What we can't do is manipulate the process's native attribute list.

You may be thinking - "Can't you just start the process, obtain its handle, and use it to add the process to the job object?" You can, and it might look something like:

using var process = new Process();
process.StartInfo.FileName = "notepad.exe";

process.Start();
// Race condition here
PInvoke.AssignProcessToJobObject(jobHandle, process.Handle);

Though, as noted above, this method technically introduces races. A process can start and immediately exit before the next instruction is reached, in which case the AssignProcessToJobObject call will certainly fail. Or a process can start and immediately spawn its own children before being added to the job object, leaving them orphaned.

These possibilities are too dangerous to ignore, which is why typical methodology involves creating the process suspended, adding it to the job object, and resuming execution.

As you can guess, starting processes suspended isn't possible with .NET at the moment. You would still have to rely on more P/Invoke to replicate this technique in C#. However, on newer versions of Windows this strategy is obsolete anyway. As Chen notes, there is a modern process attribute we can take advantage of...

PROC_THREAD_ATTRIBUTE_JOB_LIST

Permalink to “PROC_THREAD_ATTRIBUTE_JOB_LIST” #

According to the Microsoft docs, PROC_THREAD_ATTRIBUTE_JOB_LIST is a "pointer to a list of job handles to be assigned to the child process." Essentially a golden ticket for our needs (assuming you're using Windows 10 or later). By assigning the job object to our future process's extended attribute list before it is created, we can effectively avoid "hacky" solutions involving process suspension altogether.

To get started, we're going to need several more entries in NativeMethods.txt. It should now include the following:

CloseHandle
CreateJobObject
CreateProcess
DeleteProcThreadAttributeList
InitializeProcThreadAttributeList
UpdateProcThreadAttribute
PROC_THREAD_ATTRIBUTE_*
PROCESS_CREATION_FLAGS
PROCESS_INFORMATION
STARTUPINFOW
STARTUPINFOEXW

First, I'll design a minimal wrapper class to store the process's path and handle:

public sealed class Process : IDisposable
{
    public string Path { get; }
    public SafeFileHandle? SafeHandle { get; private set; }

    public Process(string path)
    {
        Path = path;
    }

    public void Dispose()
    {
        SafeHandle?.Dispose();
        SafeHandle = null;
    }
}

This class will also contain the method for actually creating the system process in a given job object. It will end up quite hefty, so I'll break it up into chunks.

The first step is determining the size of the memory needed to store our process's attribute list:

public unsafe void StartInJob(SafeFileHandle safeJobHandle)
{
    nuint size;

    _ = PInvoke.InitializeProcThreadAttributeList(
        LPROC_THREAD_ATTRIBUTE_LIST.Null, 1, 0, &size);

    nint listBuffer = Marshal.AllocHGlobal((nint)size);
    var list = (LPROC_THREAD_ATTRIBUTE_LIST)listBuffer;

This initial call to InitializeProcThreadAttributeList is expected to fail. Because we passed a null value as the first argument, along with the required number (1) of attributes our list will contain, Windows populated size with the required buffer size. We then allocated the necessary buffer size as unmanaged memory and treated it as an attribute list.

Next, we'll call the function again to initialize the list. Afterward, we can update the necessary attribute in the list with the handle to our job object:

try
{
    PInvoke.InitializeProcThreadAttributeList(list, 1, 0, &size);

    HANDLE jobHandle = (HANDLE)safeJobHandle.DangerousGetHandle();

    PInvoke.UpdateProcThreadAttribute(
        list, 0, PInvoke.PROC_THREAD_ATTRIBUTE_JOB_LIST,
        &jobHandle, (nuint)sizeof(HANDLE));

Now that the attribute list is prepared, we can use it to initialize the process's startup info. We should also ensure that our process's path is the appropriate structure.

STARTUPINFOEXW siex = new()
{
    lpAttributeList = list
};
siex.StartupInfo.cb = (uint)sizeof(STARTUPINFOEXW);

char[] cmd = (Path + '\0').ToCharArray(); // Must be null terminated
Span<char> lpCommandLine = cmd;

Because PROC_THREAD_ATTRIBUTE_JOB_LIST is an extended attribute, we needed to use a STARTUPINFOEX structure. It's essentially a wrapper for STARTUPINFO along with the attribute list for the process.

Additionally, as per the Microsoft docs, the cb member of STARTUPINFOEX.StartupInfo must be assigned the size of its wrapping structure when using an extended startup info structure.

At this point, we can finally create the process:

PROCESS_INFORMATION pi;

PInvoke.CreateProcess(
    null, ref lpCommandLine, null, null, false,
    PROCESS_CREATION_FLAGS.EXTENDED_STARTUPINFO_PRESENT,
    null, null, in siex.StartupInfo, out pi);

Note that another requirement of using extended attributes is that EXTENDED_STARTUPINFO_PRESENT must be specified in the dwCreationFlags parameter of our CreateProcess call.

In the above code block, I've declared pi explicitly for clarity. We're now going to use it to obtain a handle to the newly created process. Afterward, we'll write some final necessary cleanup.

    SafeHandle = new SafeFileHandle(pi.hProcess, ownsHandle: true);

    // Not using this. Handle must be closed.
    _ = PInvoke.CloseHandle(pi.hThread);
}
finally
{
    PInvoke.DeleteProcThreadAttributeList(list);
    Marshal.FreeHGlobal(listBuffer);
}

By passing true to the ownsHandle parameter, we relinquished ownership of the process handle and responsibility of its lifetime. At this point, our custom Process object will finally own a safe handle to the system process. When Dispose() is called on SafeHandle, .NET will take care of closing the system handle for us.

hThread, however, is a handle we have no plans of using. Technically, it will be closed by the system when its parent process terminates. Though it is still more responsible to expressly call the CloseHandle function, as seen above.

Lastly, it's vital not to forget about the attribute list and the unmanaged memory we allocated for it earlier.

The complete package

Permalink to “The complete package” #

It took awhile, but we've now constructed a custom solution that can start a system process in a given job object. Putting the whole thing together, it looks like this:

public sealed class Process : IDisposable
{
    public string Path { get; }
    public SafeFileHandle? SafeHandle { get; private set; }

    public Process(string path)
    {
        Path = path;
    }

    public unsafe void StartInJob(SafeFileHandle safeJobHandle)
    {
        nuint size;

        _ = PInvoke.InitializeProcThreadAttributeList(
            LPROC_THREAD_ATTRIBUTE_LIST.Null, 1, 0, &size);

        nint listBuffer = Marshal.AllocHGlobal((nint)size);
        var list = (LPROC_THREAD_ATTRIBUTE_LIST)listBuffer;

        try
        {
            PInvoke.InitializeProcThreadAttributeList(list, 1, 0, &size);

            HANDLE jobHandle = (HANDLE)safeJobHandle.DangerousGetHandle();

            PInvoke.UpdateProcThreadAttribute(
                list, 0, PInvoke.PROC_THREAD_ATTRIBUTE_JOB_LIST,
                &jobHandle, (nuint)sizeof(HANDLE));

            STARTUPINFOEXW siex = new()
            {
                lpAttributeList = list
            };
            siex.StartupInfo.cb = (uint)sizeof(STARTUPINFOEXW);

            char[] cmd = (Path + '\0').ToCharArray(); // Must be null terminated
            Span<char> lpCommandLine = cmd;

            PROCESS_INFORMATION pi;

            PInvoke.CreateProcess(
                null, ref lpCommandLine, null, null, false,
                PROCESS_CREATION_FLAGS.EXTENDED_STARTUPINFO_PRESENT,
                null, null, in siex.StartupInfo, out pi);

            SafeHandle = new SafeFileHandle(pi.hProcess, ownsHandle: true);

            // Not using this. Handle must be closed.
            _ = PInvoke.CloseHandle(pi.hThread);
        }
        finally
        {
            PInvoke.DeleteProcThreadAttributeList(list);
            Marshal.FreeHGlobal(listBuffer);
        }
    }

    public void Dispose()
    {
        SafeHandle?.Dispose();
        SafeHandle = null;
    }
}

Next steps in extending the class might include adding an "exited" event handler using a wait handle, but that's for another post.

A poem on software bloat

2025-11-18T05:00:00.000Z

Bloat

Permalink to “Bloat” #

Bloat is real, bloat is fake.
A giraffe has four ~~stomachs~~ ~~compartments~~.

Bloat is palpable, bloat is abstract.
A 64 KB binary is ~~not~~ bloat.

01000010 01101100 01101111 01100001 01110100
is ~~more~~ ~~less~~ than
42 6C 6F 61 74.

Bloat is unbearable, bloat is liberating.
This is ~~not~~ bloat.

Jellyfin and mergerfs in Proxmox

2025-02-10T05:00:00.000Z

This is not a tutorial for setting up Jellyfin itself.

As someone who has used Jellyfin pretty much since the initial Emby fork, I've had many years to tweak and optimize parts of my setup. After several iterations, my current configuration has been the longest serving and stablest by far.

One of its core components being mergerfs.

What is mergerfs?

Permalink to “What is mergerfs?” #

mergerfs is a FUSE based union filesystem geared towards simplifying storage and management of files across numerous commodity storage devices. It is similar to mhddfs, unionfs, and aufs. trapexit/mergerfs

If just one thing is taken away, let it be "union filesystem." Essentially, mergerfs lets you pool multiple directories or filesystems into a single mount point. There are many reasons you might want to achieve this, but my use case is for serving media and metadata for Jellyfin together efficiently.

A top-down view

Permalink to “A top-down view” #

More specifically, the media itself, located on a NAS, is mounted as an SMB share on the Proxmox host. This share is passed to the Jellyfin container as a R/O mount point. The metadata - including .nfo's, images, and subtitles - are located directly in the container.

Why merge these directories?

Permalink to “Why merge these directories?” #

While I've always preferred the concept of keeping metadata next to my media files, two deal breakers have deterred me:

Security: The media share accessed by Jellyfin must be read-only. I don't want the container to have any means to delete or alter data on my NAS. Of course, this means Jellyfin wouldn't be able to create or modify metadata next to the media.
Performance: Even if I work around the security issue, serving metadata alongside the media on mechanical hard drives could be a bit... clunky.

Using mergerfs provides a solution that is...

Secure: Messing with media files through the container is prohibited, but metadata manipulation is still allowed.
Speedy^[1]: Artwork and other metadata is served to clients much quicker on the host NVME than if they were located on the NAS.
Organized: The metadata folder structure mirrors what I'm used to.
Flexible: Kodi, Plex, Jellyfin, and Emby should all recognize my collection properly via the merged mount.

The Setup

Permalink to “The Setup” #

Keep in mind that for this setup, I'll be using my actual directories, so be sure to change them wherever appropriate.

The first piece in this equation is making sure the media share is available in the LXC. The simplest way to achieve this is by first mounting it on the Proxmox host itself.

Here's the line in my host's fstab that accomplishes that:

//nas/Media /mnt/lxc_shares/media cifs vers=3.0,_netdev,x-systemd.automount,noatime,uid=100000,gid=110000,dir_mode=0770,file_mode=0770,credentials=/etc/.smb-cred-media,defaults 0 0

Permission-wise, this line provides a couple of ways for container users to access the share. First, the root user of an unprivileged LXC has full access. In addition, LXC users that are added to the group 110000 have full access. (Thanks @jims-garage)

Since the SMB credentials are stored in a separate file, they need to be secured by executing:

sudo chown root:root /etc/.smb-cred-media
sudo chmod 600 /etc/.smb-cred-media

Next, the unprivileged Jellyfin container is given access to the host mount by adding the following line to its /etc/pve/lxc/{lxc_id}.conf config file:

mp0: /mnt/lxc_shares/media/,mp=/mnt/media,ro=1

Note the ro=1 setting that ensures the mount point is read-only.

After a quick reboot, a read-only /mnt/media mount point should pop up on the Jellyfin container.

The merge

Permalink to “The merge” #

It's important to first understand the layout of the directories involved in the merge. Here is a sample from my media mount:

/mnt/media/
├─ Movies/
│  ├─ A Goofy Movie (1995) [imdbid-tt0113198]/
│  │  ├─ A Goofy Movie (1995) [imdbid-tt0113198].mkv
│  │  ├─ trailer.mkv

and another matching sample of the meta folder located directly on the LXC:

/srv/docker-data/jellyfin/meta/
├─ Movies/
│  ├─ A Goofy Movie (1995) [imdbid-tt0113198]/
│  │  ├─ A Goofy Movie (1995) [imdbid-tt0113198].nfo
│  │  ├─ A Goofy Movie (1995) [imdbid-tt0113198].en.srt
│  │  ├─ backdrop.jpg
│  │  ├─ folder.jpg
│  │  ├─ landscape.jpg
│  │  ├─ logo.png

As you can see, the directories are perfectly mirrored, yet serve different content. The final merged directory consists of all of the content from both original directory trees.

With that, let's move on to the mergerfs configuration.

On Debian or Ubuntu, mergerfs can be installed using:

sudo apt update
sudo apt install mergerfs

After installation, really the only configuration is to modify the container's fstab. I've added the following line to mine:

/srv/docker-data/jellyfin/meta:/mnt/media /srv/docker-data/jellyfin/media fuse.mergerfs defaults,allow_other,use_ino,category.create=epmfs 0 0

Take note of the option allow_other at the end of the line, which ensures that users other than the mount-er have access to the merged directory.

After saving the fstab, the merged directory can be created and mounted via

sudo mkdir -p /srv/docker-data/jellyfin/media
sudo mount -a

leaving the final merged directory looking like this:

/srv/docker-data/jellyfin/media/
├─ Movies/
│  ├─ A Goofy Movie (1995) [imdbid-tt0113198]/
│  │  ├─ A Goofy Movie (1995) [imdbid-tt0113198].mkv
│  │  ├─ A Goofy Movie (1995) [imdbid-tt0113198].nfo
│  │  ├─ A Goofy Movie (1995) [imdbid-tt0113198].en.srt
│  │  ├─ backdrop.jpg
│  │  ├─ folder.jpg
│  │  ├─ landscape.jpg
│  │  ├─ logo.png
│  │  ├─ trailer.mkv

Because I use Docker for Jellyfin, I also edited its service file with systemctl edit docker to ensure Docker only starts after the merged directory is accessible:

[Unit]
RequiresMountsFor=/srv/docker-data/jellyfin/media
After=local-fs.target

That's pretty much all there is to it! All media is imported into Jellyfin through the merged directory. With NFO selected as the metadata saver and Save artwork into media folders enabled, Jellyfin will write metadata files to /srv/docker-data/jellyfin/meta/ through the merged directory.^[2]

mergerfs is FUSE based. User-space filesystem implementations can struggle to match the speed of traditional kernel-space due to all the context switches and sys calls in the chain of operations. Could this setup be more efficient? In theory.

But to put it bluntly, I don't find the idea of making a container privileged just to chase hypothetical performance gains really necessary. ↩︎
When adding media, a skeleton of the media's folder structure must be present in the meta directory before importing to Jellyfin. ↩︎