Implemented standard entry point bin/lrpm

Author: vrza

README.adoc

@@ -38,12 +38,13 @@ PHP-LRPM uses exponential backoff when attempting to restart a process; some pro
 
 == Non-goals
 
-Currently LRPM is not intended to run as PID 1, nor was it tested in this role.
+Currently, LRPM is not intended to run as PID 1, nor was it tested in this role.
 
 == Usage
 
-1. Implement the `ConfigurationSource`. This interface exposes a public method `loadConfiguration()`, that returns an associative array containing the configuration for all the workers (see details below).
-2. Implement the `Worker`. This interface exposes two public methods, `start()` and `cycle()`. The child process will call `start()`, passing the worker configuration as an argument, and then enter an endless loop, where it calls `cycle()`, and then checks for a shutdown condition (usually, the termination of the LRPM supervisor process). Backoff should be implemented at the end of the `cycle()` method, as we dispatch signal handlers right after `cycle()` returns. Be careful not to run a tight loop at times when cycles are not doing actual work!
+1. Implement one or more `Worker` classes. This interface exposes two public methods, `start()` and `cycle()`. The child process will call `start()`, passing the worker configuration as an argument, and then enter an endless loop, where it calls `cycle()`, and then checks for a shutdown condition (usually, the termination of the LRPM supervisor process). Backoff should be implemented at the end of the `cycle()` method, as we dispatch signal handlers right after `cycle()` returns. Be careful not to run a tight loop at times when cycles are not doing actual work!
+2. Implement the `ConfigurationSource` class. This interface exposes a public method `loadConfiguration()`, that returns an associative array containing the configuration for all the workers (see example and full documentation in the `Job configuration` subsection).
+3. Run `bin/rlpm` with your configuration class as an argument, e.g.  `bin/rlpm '\MyNamespace\MyConfigurationSource'`
 
 === Job configuration
 
@@ -116,9 +117,11 @@ Worker process installs default signal handlers for SIGTERM and SIGINT. Signal h
 
 You can implement and install your own signal handlers inside your Worker implementation, but make sure that your Worker process shuts down cleanly after receiving SIGTERM, otherwise the LRPM supervisor will consider it unresponsive and follow up with a SIGKILL.
 
-=== Misc caveats
+=== Implementing a custom entry point
 
-Be aware that code in your entry point will run in the supervisor (parent) process, while your `Worker` classes will run in child processes. The entry point should do no more than set up the autoloader and run the `ProcessManager`. Sharing open sockets between parent and children through `fork(2)` is not safe. Worker processes should connect to wherever they need to connect to only after they have been spawned.
+If you need to implement a custom entry point for LRPM, be aware that the code in your custom entry point will run in the supervisor (parent) process, while your `Worker` classes will run in child processes `fork(2)`-ed from the supervisor. The entry point should do no more than set up the autoloader and run the `ProcessManager`. Any open file descriptors apart from stdin/stdout/stderr should be closed before entering the event loop (`ProcessManager->run()`). Sharing open sockets between parent and children through `fork(2)` is not safe! Worker processes should connect to wherever they need to connect to only after they have been spawned.
+
+If unsure, use the provided `bin/lrpm` entry point.
 
 == Operating LRPM
 

README.in.adoc

@@ -38,12 +38,13 @@ PHP-LRPM uses exponential backoff when attempting to restart a process; some pro
 
 == Non-goals
 
-Currently LRPM is not intended to run as PID 1, nor was it tested in this role.
+Currently, LRPM is not intended to run as PID 1, nor was it tested in this role.
 
 == Usage
 
-1. Implement the `ConfigurationSource`. This interface exposes a public method `loadConfiguration()`, that returns an associative array containing the configuration for all the workers (see details below).
-2. Implement the `Worker`. This interface exposes two public methods, `start()` and `cycle()`. The child process will call `start()`, passing the worker configuration as an argument, and then enter an endless loop, where it calls `cycle()`, and then checks for a shutdown condition (usually, the termination of the LRPM supervisor process). Backoff should be implemented at the end of the `cycle()` method, as we dispatch signal handlers right after `cycle()` returns. Be careful not to run a tight loop at times when cycles are not doing actual work!
+1. Implement one or more `Worker` classes. This interface exposes two public methods, `start()` and `cycle()`. The child process will call `start()`, passing the worker configuration as an argument, and then enter an endless loop, where it calls `cycle()`, and then checks for a shutdown condition (usually, the termination of the LRPM supervisor process). Backoff should be implemented at the end of the `cycle()` method, as we dispatch signal handlers right after `cycle()` returns. Be careful not to run a tight loop at times when cycles are not doing actual work!
+2. Implement the `ConfigurationSource` class. This interface exposes a public method `loadConfiguration()`, that returns an associative array containing the configuration for all the workers (see example and full documentation in the `Job configuration` subsection).
+3. Run `bin/rlpm` with your configuration class as an argument, e.g.  `bin/rlpm '\MyNamespace\MyConfigurationSource'`
 
 === Job configuration
 
@@ -79,9 +80,11 @@ Worker process installs default signal handlers for SIGTERM and SIGINT. Signal h
 
 You can implement and install your own signal handlers inside your Worker implementation, but make sure that your Worker process shuts down cleanly after receiving SIGTERM, otherwise the LRPM supervisor will consider it unresponsive and follow up with a SIGKILL.
 
-=== Misc caveats
+=== Implementing a custom entry point
 
-Be aware that code in your entry point will run in the supervisor (parent) process, while your `Worker` classes will run in child processes. The entry point should do no more than set up the autoloader and run the `ProcessManager`. Sharing open sockets between parent and children through `fork(2)` is not safe. Worker processes should connect to wherever they need to connect to only after they have been spawned.
+If you need to implement a custom entry point for LRPM, be aware that the code in your custom entry point will run in the supervisor (parent) process, while your `Worker` classes will run in child processes `fork(2)`-ed from the supervisor. The entry point should do no more than set up the autoloader and run the `ProcessManager`. Any open file descriptors apart from stdin/stdout/stderr should be closed before entering the event loop (`ProcessManager->run()`). Sharing open sockets between parent and children through `fork(2)` is not safe! Worker processes should connect to wherever they need to connect to only after they have been spawned.
+
+If unsure, use the provided `bin/lrpm` entry point.
 
 == Operating LRPM
 

bin/lrpm

@@ -0,0 +1,64 @@
+#!/usr/bin/env php
+<?php
+declare(strict_types=1);
+error_reporting(E_ALL);
+
+const EXIT_SUCCESS = 0;
+const EXIT_USAGE = 64;
+const EXIT_AUTOLOADER_NOT_FOUND = 1;
+const EXIT_CONFIG_SOURCE_CLASS_NOT_FOUND = 2;
+
+$shortopts = 'h';
+$longopts = [
+    'help'
+];
+$options = getopt($shortopts, $longopts, $rest_index);
+$progname = basename($argv[0]);
+$helpmsg = "Usage: $progname [options] <configuration-class>
+
+Options:
+  -h, --help         display this help and exit
+";
+
+if (array_key_exists('h', $options) || array_key_exists('help', $options)) {
+    fwrite(STDERR, $helpmsg);
+    exit(EXIT_USAGE);
+}
+
+$rest = array_slice($argv, $rest_index);
+if (count($rest) < 1) {
+    fwrite(STDERR, $helpmsg);
+    exit(EXIT_USAGE);
+}
+
+$configSourceClass = $rest[0];
+
+probeForAutoloader($progname);
+
+if (!class_exists($configSourceClass)) {
+    fwrite(STDERR, "Cannot find class: $configSourceClass" . PHP_EOL);
+    exit(EXIT_CONFIG_SOURCE_CLASS_NOT_FOUND);
+}
+
+use PHPLRPM\ProcessManager;
+
+$processManager = new ProcessManager($configSourceClass);
+$processManager->run();
+
+function probeForAutoloader($programName): void
+{
+    $autoloadLocations = [
+        __DIR__ . '/../vendor/autoload.php',
+        __DIR__ . '/../../../autoload.php'
+    ];
+
+    foreach ($autoloadLocations as $autoloadFile) {
+        if (file_exists($autoloadFile)) {
+            require_once($autoloadFile);
+            return;
+        }
+    }
+
+    fwrite(STDERR, $programName . ': could not find autoload.php, use PHP Composer to generate autoloader code' . PHP_EOL);
+    exit(EXIT_AUTOLOADER_NOT_FOUND);
+}

bin/lrpmctl

@@ -18,7 +18,7 @@ $longopts = [
 ];
 $options = getopt($shortopts, $longopts, $rest_index);
 $progname = basename($argv[0]);
-$helpmsg = "Usage: $progname [<options>] <message>
+$helpmsg = "Usage: $progname [options] <message>
 
 Options:
   -h, --help         display this help and exit