Dynamic instantiation under s6

A instanced service is a parameterized service that you want to run several copies of, with only the parameter changing. Each copy of the service is called an instance.

With s6, a service directory can only handle one process at a time. So, if we want instanced services, there will have to be one service directory per instance, always.

Static instantiation means that the set of possible instances is finite and known in advance. With s6, it means that all the service directories for all possible instances are created, typically by a preprocessor, and instances are treated like regular services.

Dynamic instantiation means that instances are created on demand instead of preallocated. Starting with version 2.11.2.0, s6 provides a few tools to help users set up and manage dynamically instanced services.

How to make a dynamically instanced service under s6

Write a template for a service directory that would run under s6-supervise. The run script should take the name of the instance as its first argument; the finish script should take the name of the instance as its third argument.
Call the s6-instance-maker program with this template as first argument, and a path dir as second argument. s6-instance-maker will create a service directory in dir. This is an offline tool: it does not interact with any currently active services or supervision trees.
Supervise dir by adding it to your regular scan directory. This will be your instanced service, but it's not running any instances yet. It is, instead, a nested supervision tree - the instanced service is an s6-svscan process that will supervise all the instances.
Create and delete instances at will with the s6-instance-create and s6-instance-delete programs. Instances are regular supervised processes; you can control them with s6-instance-control. These tools are online: they work with live service directories (i.e. that are being supervised by s6-supervise). They are really syntactic sugar around the s6-svlink, s6-svunlink and s6-svc programs; they provide you with the same functionality but allow you to address individual instances via the instanced service name (the service directory running the nested supervision tree) and the instance name.

Internal workings

This section is not normative; users should not rely on it. It is only here for informational purposes.

The service directory created by s6-instance-maker has two specifics subdirectories in it: instance and instances. They are initially empty, except that the template service directory is stored in instances/.template.
When the service is active, there is an s6-svscan process running on instance.
s6-instance-create makes a copy of instances/.template into instances/name, and s6-svlinks instances/name to instance. When it returns, there is an s6-supervise process running on instance/name, and the instance may be up or not depending on the given options.
s6-instance-control is syntactic sugar around s6-svc on instance/name.
s6-instance-delete is syntactic sugar around s6-svunlink on instance/name.

Notes

This implementation of dynamic instances may seem expensive: it creates one s6-svscan process per instanced service, and one s6-supervise process per instance. However, remember that these processes use very little private memory, so having additional copies of them is far less expensive than it looks. It's really a convenient way to implement the feature by reusing existing code.