instances.html (5540B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>s6: dynamic instantiation</title> 7 <meta name="Description" content="s6: dynamic instantiation" /> 8 <meta name="Keywords" content="s6 instances dynamic instantiation" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">s6</a><br /> 15 <a href="//skarnet.org/software/">Software</a><br /> 16 <a href="//skarnet.org/">skarnet.org</a> 17 </p> 18 19 <h1> Dynamic instantiation </h1> 20 21 <p> 22 An <em>instanced service</em> is a parameterized service that you want to 23 run several copies of, with only the parameter changing. Each copy of the 24 service is called an <em>instance</em>. 25 </p> 26 27 <p> 28 With s6, a <a href="servicedir.html">service directory</a> can only 29 handle one process at a time. So, if we want instanced services, there 30 will have to be one service directory per instance, always. 31 </p> 32 33 <p> 34 <em>Static instantiation</em> means that the set of possible instances 35 is finite and known in advance. With s6, it means that all the service 36 directories for all possible instances are created, typically by a 37 preprocessor, and instances are treated like regular services. 38 </p> 39 40 <p> 41 <em>Dynamic instantiation</em> means that instances are created 42 on demand instead of preallocated. Starting with version 2.11.2.0, s6 43 provides a few tools to help users set up and manage dynamically 44 instanced services. 45 </p> 46 47 <h2> How to make a dynamically instanced service under s6 </h2> 48 49 <ul> 50 <li> Write a template for a service directory that would run under 51 <a href="s6-supervise.html">s6-supervise</a>. 52 The <tt>run</tt> script should take the name of the instance as its 53 first argument; the <tt>finish</tt> script, if present, should take the name 54 of the instance as its third argument. </li> 55 <li> Call the <a href="s6-instance-maker.html">s6-instance-maker</a> program 56 with this template as first argument, and a path <em>dir</em> as second 57 argument. <a href="s6-instance-maker.html">s6-instance-maker</a> will create 58 a service directory in <em>dir</em>. This is an offline tool: it does not 59 interact with any currently active services or supervision trees. </li> 60 <li> Supervise <em>dir</em> by adding it to your regular 61 <a href="scandir.html">scan directory</a>. This will be your instanced 62 service, but it's not running any instances yet. It is, instead, a nested 63 supervision tree - the instanced service is an 64 <a href="s6-svscan.html">s6-svscan</a> process that will supervise all the 65 instances. </li> 66 <li> Create and delete instances at will with the 67 <a href="s6-instance-create.html">s6-instance-create</a> and 68 <a href="s6-instance-delete.html">s6-instance-delete</a> programs; you 69 can list all the available instances with 70 <a href="s6-instance-list.html">s6-instance-list</a>. 71 These tools are <em>online</em>: they work with live service directories, 72 i.e. that are being supervised by <a href="s6-supervise.html">s6-supervise</a>. 73 <li> Instances are regular supervised processes. You can control individual 74 instances with <a href="s6-instance-control.html">s6-instance-control</a>, 75 and check their status with 76 <a href="s6-instance-status.html">s6-instance-status</a>. These tools 77 are online as well. </li> 78 </ul> 79 80 <h2> Internal workings </h2> 81 82 <p> 83 This section is not normative; users should not rely on it. It is only 84 here for informational purposes. 85 </p> 86 87 <ul> 88 <li> The service directory created by <a href="s6-instance-maker.html">s6-instance-maker</a> 89 has three specific subdirectories in it: <tt>instance</tt> and <tt>instances</tt>, which 90 are initially empty, and <tt>template</tt>, storing the template service directory. </li> 91 <li> When the service is active, there is an <a href="s6-svscan.html">s6-svscan</a> 92 process running on <tt>instance</tt>. </li> 93 <li> <a href="s6-instance-create.html">s6-instance-create</a> makes a copy of 94 <tt>template</tt> into <tt>instances/<em>name</em></tt>, and 95 <a href="s6-svlink.html">s6-svlink</a>s <tt>instances/<em>name</em></tt> to 96 <tt>instance</tt>. When it returns, there is an <a href="s6-supervise.html">s6-supervise</a> 97 process running on <tt>instance/<em>name</em></tt>, and the instance may be up 98 or not depending on the given options. </li> 99 <li> <a href="s6-instance-control.html">s6-instance-control</a> is syntactic sugar 100 around <a href="s6-svc.html">s6-svc</a> on <tt>instance/<em>name</em></tt>. </li> 101 <li> <a href="s6-instance-status.html">s6-instance-status</a> is syntactic sugar 102 around <a href="s6-svstat.html">s6-svstat</a> on <tt>instance/<em>name</em></tt>. </li> 103 <li> <a href="s6-instance-delete.html">s6-instance-delete</a> is syntactic sugar 104 around <a href="s6-svunlink.html">s6-svunlink</a> on <tt>instance/<em>name</em></tt>. </li> 105 <li> <a href="s6-instance-list.html">s6-instance-list</a> is roughly equivalent 106 to <code>ls -1 instance </code>. </li> 107 </ul> 108 109 <h2> Notes </h2> 110 111 <ul> 112 <li> This implementation of dynamic instances may seem expensive: it 113 creates one <a href="s6-svscan.html">s6-svscan</a> process per 114 instanced service, and one <a href="s6-supervise.html">s6-supervise</a> 115 process per instance. However, remember that these processes use very 116 little private memory, so having additional copies of them is far less 117 expensive than it looks. It's really a convenient way to implement the 118 feature by reusing existing code. </li> 119 </ul> 120 121 </body> 122 </html>