«Child Process» и «Beanstalk Protocol»: разница между страницами

Материал из support.qbpro.ru
(Различия между страницами)
imported>Supportadmin
 
imported>Supportadmin
(Новая страница: « = Beanstalk Protocol = Protocol -------- The beanstalk protocol runs over TCP using ASCII encoding. Clients connect, send commands and data, wait for responses…»)
 
Строка 1: Строка 1:
'''''Stability: 3 - Stable'''''


Node обеспечивает трёх-направленный POPEN (3) для модуля child_process.
= Beanstalk Protocol =


Поток данных можно направлять через стандартные stdin, stdout и stderr дочернего процесса в полностью неблокирующем стиле. (Заметим, что некоторые программы используют внутреннюю линейную буферизации строк ввода/вывода. Это не влияет node.js, но это означает что информация, передаваемая дочернему процессу "потребляется" им не сразу.)
Protocol
--------


Для создания дочернего процесса используйте require('child_process').spawn() или require('child_process').fork(). Семантика каждого немного отличается, и описана ниже.
The beanstalk protocol runs over TCP using ASCII encoding. Clients connect,
send commands and data, wait for responses, and close the connection. For each
connection, the server processes commands serially in the order in which they
were received and sends responses in the same order. All integers in the
protocol are formatted in decimal and (unless otherwise indicated)
nonnegative.


==Class: ChildProcess==
Names, in this protocol, are ASCII strings. They may contain letters (A-Z and
ChildProcess is an EventEmitter.
a-z), numerals (0-9), hyphen ("-"), plus ("+"), slash ("/"), semicolon (";"),
dot ("."), dollar-sign ("$"), underscore ("_"), and parentheses ("(" and ")"),
but they may not begin with a hyphen. They are terminated by white space
(either a space char or end of line). Each name must be at least one character
long.


Child processes always have three streams associated with them. child.stdin, child.stdout, and child.stderr. These may be shared with the stdio streams of the parent process, or they may be separate stream objects which can be piped to and from.
The protocol contains two kinds of data: text lines and unstructured chunks of
data. Text lines are used for client commands and server responses. Chunks are
used to transfer job bodies and stats information. Each job body is an opaque
sequence of bytes. The server never inspects or modifies a job body and always
sends it back in its original form. It is up to the clients to agree on a
meaningful interpretation of job bodies.


The ChildProcess class is not intended to be used directly. Use the spawn() or fork() methods to create a Child Process instance.
The client may issue the "quit" command, or simply close the TCP connection
when it no longer has use for the server. However, beanstalkd performs very
well with a large number of open connections, so it is usually better for the
client to keep its connection open and reuse it as much as possible. This also
avoids the overhead of establishing new TCP connections.


===Event: 'error'===
If a client violates the protocol (such as by sending a request that is not
err Error Object the error.
well-formed or a command that does not exist) or if the server has an error,
Emitted when:
the server will reply with one of the following error messages:


The process could not be spawned, or
- "OUT_OF_MEMORY\r\n" The server cannot allocate enough memory for the job.
The process could not be killed, or
  The client should try again later.
Sending a message to the child process failed for whatever reason.
See also ChildProcess#kill() and ChildProcess#send().


===Event: 'exit'===
- "INTERNAL_ERROR\r\n" This indicates a bug in the server. It should never
code Number the exit code, if it exited normally.
  happen. If it does happen, please report it at
signal String the signal passed to kill the child process, if it was killed by the parent.
  http://groups.google.com/group/beanstalk-talk.
This event is emitted after the child process ends. If the process terminated normally, code is the final exit code of the process, otherwise null. If the process terminated due to receipt of a signal, signal is the string name of the signal, otherwise null.


Note that the child process stdio streams might still be open.
- "BAD_FORMAT\r\n" The client sent a command line that was not well-formed.
  This can happen if the line does not end with \r\n, if non-numeric
  characters occur where an integer is expected, if the wrong number of
  arguments are present, or if the command line is mal-formed in any other
  way.


See waitpid(2).
- "UNKNOWN_COMMAND\r\n" The client sent a command that the server does not
  know.


===Event: 'close'===
These error responses will not be listed in this document for individual
code Number the exit code, if it exited normally.
commands in the following sections, but they are implicitly included in the
signal String the signal passed to kill the child process, if it was killed by the parent.
description of all commands. Clients should be prepared to receive an error
This event is emitted when the stdio streams of a child process have all terminated. This is distinct from 'exit', since multiple processes might share the same stdio streams.
response after any command.


===Event: 'disconnect'===
As a last resort, if the server has a serious error that prevents it from
This event is emitted after using the .disconnect() method in the parent or in the child. After disconnecting it is no longer possible to send messages. An alternative way to check if you can send messages is to see if the child.connected property is true.
continuing service to the current client, the server will close the
connection.


===Event: 'message'===
Job Lifecycle
message Object a parsed JSON object or primitive value
-------------
sendHandle Handle object a Socket or Server object
Messages send by .send(message, [sendHandle]) are obtained using the message event.


====child.stdin====
A job in beanstalk gets created by a client with the "put" command. During its
Stream object
life it can be in one of four states: "ready", "reserved", "delayed", or
A Writable Stream that represents the child process's stdin. Closing this stream via end() often causes the child process to terminate.
"buried". After the put command, a job typically starts out ready. It waits in
the ready queue until a worker comes along and runs the "reserve" command. If
this job is next in the queue, it will be reserved for the worker. The worker
will execute the job; when it is finished the worker will send a "delete"
command to delete the job.


If the child stdio streams are shared with the parent, then this will not be set.
Here is a picture of the typical job lifecycle:


====child.stdout====
Stream object
A Readable Stream that represents the child process's stdout.


If the child stdio streams are shared with the parent, then this will not be set.
  put            reserve              delete
  -----> [READY] ---------> [RESERVED] --------> *poof*


====child.stderr====
Stream object
A Readable Stream that represents the child process's stderr.


If the child stdio streams are shared with the parent, then this will not be set.


====child.pid====
Here is a picture with more possibilities:
'''Integer'''


The PID of the child process.


Example:


<nowiki>var spawn = require('child_process').spawn,
  put with delay              release with delay
     grep = spawn('grep', ['ssh']);
  ----------------> [DELAYED] <------------.
                        |                  |
                        | (time passes)     |
                        |                  |
  put                  v     reserve      |      delete
  -----------------> [READY] ---------> [RESERVED] --------> *poof*
                      ^ ^                |  |
                      |  \  release      |  |
                      |    `-------------'   |
                      |                      |
                      | kick                |
                      |                      |
                      |      bury          |
                    [BURIED] <---------------'
                      |
                      |  delete
                        `--------> *poof*


console.log('Spawned child pid: ' + grep.pid);
grep.stdin.end();</nowiki>
====child.kill([signal])====
'''signal String'''


Send a signal to the child process. If no argument is given, the process will be sent 'SIGTERM'. See signal(7) for a list of available signals.
The system has one or more tubes. Each tube consists of a ready queue and a
delay queue. Each job spends its entire life in one tube. Consumers can show
interest in tubes by sending the "watch" command; they can show disinterest by
sending the "ignore" command. This set of interesting tubes is said to be a
consumer's "watch list". When a client reserves a job, it may come from any of
the tubes in its watch list.


<nowiki>var spawn = require('child_process').spawn,
When a client connects, its watch list is initially just the tube named
    grep  = spawn('grep', ['ssh']);
"default". If it submits jobs without having sent a "use" command, they will
live in the tube named "default".


grep.on('close', function (code, signal) {
Tubes are created on demand whenever they are referenced. If a tube is empty
  console.log('child process terminated due to receipt of signal '+signal);
(that is, it contains no ready, delayed, or buried jobs) and no client refers
});
to it, it will be deleted.


// send SIGHUP to process
Producer Commands
grep.kill('SIGHUP');</nowiki>
-----------------


May emit an 'error' event when the signal cannot be delivered. Sending a signal to a child process that has already exited is not an error but may have unforeseen consequences: if the PID (the process ID) has been reassigned to another process, the signal will be delivered to that process instead. What happens next is anyone's guess.
The "put" command is for any process that wants to insert a job into the queue.
It comprises a command line followed by the job body:


Note that while the function is called kill, the signal delivered to the child process may not actually kill it. kill really just sends a signal to a process.
put <pri> <delay> <ttr> <bytes>\r\n
<data>\r\n


See kill(2)
It inserts a job into the client's currently used tube (see the "use" command
below).


====child.send(message, [sendHandle])====
- <pri> is an integer < 2**32. Jobs with smaller priority values will be
'''message Object'''
  scheduled before jobs with larger priorities. The most urgent priority is 0;
  the least urgent priority is 4,294,967,295.


'''sendHandle Handle object'''
- <delay> is an integer number of seconds to wait before putting the job in
  the ready queue. The job will be in the "delayed" state during this time.


When using child_process.fork() you can write to the child using child.send(message, [sendHandle]) and messages are received by a 'message' event on the child.
- <ttr> -- time to run -- is an integer number of seconds to allow a worker
  to run this job. This time is counted from the moment a worker reserves
  this job. If the worker does not delete, release, or bury the job within
  <ttr> seconds, the job will time out and the server will release the job.
  The minimum ttr is 1. If the client sends 0, the server will silently
  increase the ttr to 1.


For example:
- <bytes> is an integer indicating the size of the job body, not including the
  trailing "\r\n". This value must be less than max-job-size (default: 2**16).


  <nowiki>var cp = require('child_process');
  - <data> is the job body -- a sequence of bytes of length <bytes> from the
  previous line.


var n = cp.fork(__dirname + '/sub.js');
After sending the command line and body, the client waits for a reply, which
may be:


n.on('message', function(m) {
- "INSERTED <id>\r\n" to indicate success.
  console.log('PARENT got message:', m);
});


n.send({ hello: 'world' });</nowiki>
  - <id> is the integer id of the new job
And then the child script, 'sub.js' might look like this:


  <nowiki>process.on('message', function(m) {
  - "BURIED <id>\r\n" if the server ran out of memory trying to grow the
  console.log('CHILD got message:', m);
  priority queue data structure.
});


process.send({ foo: 'bar' });</nowiki>
  - <id> is the integer id of the new job
In the child the process object will have a send() method, and process will emit objects each time it receives a message on its channel.


There is a special case when sending a {cmd: 'NODE_foo'} message. All messages containing a NODE_ prefix in its cmd property will not be emitted in the message event, since they are internal messages used by node core. Messages containing the prefix are emitted in the internalMessage event, you should by all means avoid using this feature, it is subject to change without notice.
- "EXPECTED_CRLF\r\n" The job body must be followed by a CR-LF pair, that is,
  "\r\n". These two bytes are not counted in the job size given by the client
  in the put command line.


The sendHandle option to child.send() is for sending a TCP server or socket object to another process. The child will receive the object as its second argument to the message event.
- "JOB_TOO_BIG\r\n" The client has requested to put a job with a body larger
  than max-job-size bytes.


Emits an 'error' event if the message cannot be sent, for example because the child process has already exited.
- "DRAINING\r\n" This means that the server has been put into "drain mode"
  and is no longer accepting new jobs. The client should try another server
  or disconnect and try again later.


====Example: sending server object====
The "use" command is for producers. Subsequent put commands will put jobs into
the tube specified by this command. If no use command has been issued, jobs
will be put into the tube named "default".


Here is an example of sending a server:
use <tube>\r\n


  <nowiki>var child = require('child_process').fork('child.js');
  - <tube> is a name at most 200 bytes. It specifies the tube to use. If the
  tube does not exist, it will be created.


// Open up the server object and send the handle.
The only reply is:
var server = require('net').createServer();
server.on('connection', function (socket) {
  socket.end('handled by parent');
});
server.listen(1337, function() {
  child.send('server', server);
});</nowiki>
And the child would the receive the server object as:


<nowiki>process.on('message', function(m, server) {
USING <tube>\r\n
  if (m === 'server') {
    server.on('connection', function (socket) {
      socket.end('handled by child');
    });
  }
});</nowiki>


Note that the server is now shared between the parent and child, this means that some connections will be handled by the parent and some by the child.
- <tube> is the name of the tube now being used.


For dgram servers the workflow is exactly the same. Here you listen on a message event instead of connection and use server.bind instead of server.listen. (Currently only supported on UNIX platforms.)
Worker Commands
---------------


====Example: sending socket object====
A process that wants to consume jobs from the queue uses "reserve", "delete",
"release", and "bury". The first worker command, "reserve", looks like this:


Here is an example of sending a socket. It will spawn two children and handle connections with the remote address 74.125.127.100 as VIP by sending the socket to a "special" child process. Other sockets will go to a "normal" process.
reserve\r\n


<nowiki>var normal = require('child_process').fork('child.js', ['normal']);
Alternatively, you can specify a timeout as follows:
var special = require('child_process').fork('child.js', ['special']);


// Open up the server and send sockets to child
reserve-with-timeout <seconds>\r\n
var server = require('net').createServer();
server.on('connection', function (socket) {


  // if this is a VIP
This will return a newly-reserved job. If no job is available to be reserved,
  if (socket.remoteAddress === '74.125.127.100') {
beanstalkd will wait to send a response until one becomes available. Once a
    special.send('socket', socket);
job is reserved for the client, the client has limited time to run (TTR) the
    return;
job before the job times out. When the job times out, the server will put the
  }
job back into the ready queue. Both the TTR and the actual time left can be
  // just the usual dudes
found in response to the stats-job command.
  normal.send('socket', socket);
});
server.listen(1337);</nowiki>
The child.js could look like this:


<nowiki>process.on('message', function(m, socket) {
If more than one job is ready, beanstalkd will choose the one with the
  if (m === 'socket') {
smallest priority value. Within each priority, it will choose the one that
    socket.end('You were handled as a ' + process.argv[2] + ' person');
was received first.
  }
});</nowiki>
Note that once a single socket has been sent to a child the parent can no longer keep track of when the socket is destroyed. To indicate this condition the .connections property becomes null. It is also recommended not to use .maxConnections in this condition.


===child.disconnect()===
A timeout value of 0 will cause the server to immediately return either a
To close the IPC connection between parent and child use the child.disconnect() method. This allows the child to exit gracefully since there is no IPC channel keeping it alive. When calling this method the disconnect event will be emitted in both parent and child, and the connected flag will be set to false. Please note that you can also call process.disconnect() in the child process.
response or TIMED_OUT. A positive value of timeout will limit the amount of
time the client will block on the reserve request until a job becomes
available.


===child_process.spawn(command, [args], [options])===
During the TTR of a reserved job, the last second is kept by the server as a
command String The command to run
safety margin, during which the client will not be made to wait for another
job. If the client issues a reserve command during the safety margin, or if
the safety margin arrives while the client is waiting on a reserve command,
the server will respond with:


args Array List of string arguments
DEADLINE_SOON\r\n


options Object
This gives the client a chance to delete or release its reserved job before
the server automatically releases it.


cwd String Current working directory of the child process
TIMED_OUT\r\n
stdio Array|String Child's stdio configuration. (See below)
customFds Array Deprecated File descriptors for the child to use for stdio. (See below)
env Object Environment key-value pairs
detached Boolean The child will be a process group leader. (See below)
uid Number Sets the user identity of the process. (See setuid(2).)
gid Number Sets the group identity of the process. (See setgid(2).)
return: ChildProcess object
Launches a new process with the given command, with command line arguments in args. If omitted, args defaults to an empty Array.


The third argument is used to specify additional options, which defaults to:
If a non-negative timeout was specified and the timeout exceeded before a job
became available, or if the client's connection is half-closed, the server
will respond with TIMED_OUT.


{ cwd: undefined,
Otherwise, the only other response to this command is a successful reservation
  env: process.env
in the form of a text line followed by the job body:
}
cwd allows you to specify the working directory from which the process is spawned. Use env to specify environment variables that will be visible to the new process.


Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:
RESERVED <id> <bytes>\r\n
<data>\r\n


var spawn = require('child_process').spawn,
- <id> is the job id -- an integer unique to this job in this instance of
    ls   = spawn('ls', ['-lh', '/usr']);
   beanstalkd.


ls.stdout.on('data', function (data) {
- <bytes> is an integer indicating the size of the job body, not including
  console.log('stdout: ' + data);
  the trailing "\r\n".
});


ls.stderr.on('data', function (data) {
- <data> is the job body -- a sequence of bytes of length <bytes> from the
  console.log('stderr: ' + data);
  previous line. This is a verbatim copy of the bytes that were originally
});
  sent to the server in the put command for this job.


ls.on('close', function (code) {
The delete command removes a job from the server entirely. It is normally used
  console.log('child process exited with code ' + code);
by the client when the job has successfully run to completion. A client can
});
delete jobs that it has reserved, ready jobs, delayed jobs, and jobs that are
Example: A very elaborate way to run 'ps ax | grep ssh'
buried. The delete command looks like this:


var spawn = require('child_process').spawn,
delete <id>\r\n
    ps    = spawn('ps', ['ax']),
    grep  = spawn('grep', ['ssh']);


ps.stdout.on('data', function (data) {
- <id> is the job id to delete.
  grep.stdin.write(data);
});


ps.stderr.on('data', function (data) {
The client then waits for one line of response, which may be:
  console.log('ps stderr: ' + data);
});


ps.on('close', function (code) {
- "DELETED\r\n" to indicate success.
  if (code !== 0) {
    console.log('ps process exited with code ' + code);
  }
  grep.stdin.end();
});


grep.stdout.on('data', function (data) {
- "NOT_FOUND\r\n" if the job does not exist or is not either reserved by the
  console.log('' + data);
  client, ready, or buried. This could happen if the job timed out before the
});
  client sent the delete command.


grep.stderr.on('data', function (data) {
The release command puts a reserved job back into the ready queue (and marks
  console.log('grep stderr: ' + data);
its state as "ready") to be run by any client. It is normally used when the job
});
fails because of a transitory error. It looks like this:


grep.on('close', function (code) {
release <id> <pri> <delay>\r\n
  if (code !== 0) {
    console.log('grep process exited with code ' + code);
  }
});
Example of checking for failed exec:


var spawn = require('child_process').spawn,
- <id> is the job id to release.
    child = spawn('bad_command');


child.stderr.setEncoding('utf8');
- <pri> is a new priority to assign to the job.
child.stderr.on('data', function (data) {
  if (/^execvp\(\)/.test(data)) {
    console.log('Failed to start child process.');
  }
});
Note that if spawn receives an empty options object, it will result in spawning the process with an empty environment rather than using process.env. This due to backwards compatibility issues with a deprecated API.


The 'stdio' option to child_process.spawn() is an array where each index corresponds to a fd in the child. The value is one of the following:
- <delay> is an integer number of seconds to wait before putting the job in
  the ready queue. The job will be in the "delayed" state during this time.


'pipe' - Create a pipe between the child process and the parent process. The parent end of the pipe is exposed to the parent as a property on the child_process object as ChildProcess.stdio[fd]. Pipes created for fds 0 - 2 are also available as ChildProcess.stdin, ChildProcess.stdout and ChildProcess.stderr, respectively.
The client expects one line of response, which may be:
'ipc' - Create an IPC channel for passing messages/file descriptors between parent and child. A ChildProcess may have at most one IPC stdio file descriptor. Setting this option enables the ChildProcess.send() method. If the child writes JSON messages to this file descriptor, then this will trigger ChildProcess.on('message'). If the child is a Node.js program, then the presence of an IPC channel will enable process.send() and process.on('message').
'ignore' - Do not set this file descriptor in the child. Note that Node will always open fd 0 - 2 for the processes it spawns. When any of these is ignored node will open /dev/null and attach it to the child's fd.
Stream object - Share a readable or writable stream that refers to a tty, file, socket, or a pipe with the child process. The stream's underlying file descriptor is duplicated in the child process to the fd that corresponds to the index in the stdio array.
Positive integer - The integer value is interpreted as a file descriptor that is is currently open in the parent process. It is shared with the child process, similar to how Stream objects can be shared.
null, undefined - Use default value. For stdio fds 0, 1 and 2 (in other words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the default is 'ignore'.
As a shorthand, the stdio argument may also be one of the following strings, rather than an array:


ignore - ['ignore', 'ignore', 'ignore']
- "RELEASED\r\n" to indicate success.
pipe - ['pipe', 'pipe', 'pipe']
inherit - [process.stdin, process.stdout, process.stderr] or [0,1,2]
Example:


var spawn = require('child_process').spawn;
- "BURIED\r\n" if the server ran out of memory trying to grow the priority
  queue data structure.


// Child will use parent's stdios
- "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
spawn('prg', [], { stdio: 'inherit' });


// Spawn child sharing only stderr
The bury command puts a job into the "buried" state. Buried jobs are put into a
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] });
FIFO linked list and will not be touched by the server again until a client
kicks them with the "kick" command.


// Open an extra fd=4, to interact with programs present a
The bury command looks like this:
// startd-style interface.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] });
If the detached option is set, the child process will be made the leader of a new process group. This makes it possible for the child to continue running after the parent exits.


By default, the parent will wait for the detached child to exit. To prevent the parent from waiting for a given child, use the child.unref() method, and the parent's event loop will not include the child in its reference count.
bury <id> <pri>\r\n


Example of detaching a long-running process and redirecting its output to a file:
- <id> is the job id to release.


  var fs = require('fs'),
  - <pri> is a new priority to assign to the job.
    spawn = require('child_process').spawn,
    out = fs.openSync('./out.log', 'a'),
    err = fs.openSync('./out.log', 'a');


var child = spawn('prg', [], {
There are two possible responses:
  detached: true,
  stdio: [ 'ignore', out, err ]
});


  child.unref();
  - "BURIED\r\n" to indicate success.
When using the detached option to start a long-running process, the process will not stay running in the background unless it is provided with a stdio configuration that is not connected to the parent. If the parent's stdio is inherited, the child will remain attached to the controlling terminal.


There is a deprecated option called customFds which allows one to specify specific file descriptors for the stdio of the child process. This API was not portable to all platforms and therefore removed. With customFds it was possible to hook up the new process' [stdin, stdout, stderr] to existing streams; -1 meant that a new stream should be created. Use at your own risk.
- "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.


See also: child_process.exec() and child_process.fork()
The "touch" command allows a worker to request more time to work on a job.
This is useful for jobs that potentially take a long time, but you still want
the benefits of a TTR pulling a job away from an unresponsive worker.  A worker
may periodically tell the server that it's still alive and processing a job
(e.g. it may do this on DEADLINE_SOON). The command postpones the auto
release of a reserved job until TTR seconds from when the command is issued.


child_process.exec(command, [options], callback)#
The touch command looks like this:
command String The command to run, with space-separated arguments
options Object
cwd String Current working directory of the child process
env Object Environment key-value pairs
encoding String (Default: 'utf8')
timeout Number (Default: 0)
maxBuffer Number (Default: 200*1024)
killSignal String (Default: 'SIGTERM')
callback Function called with the output when process terminates
error Error
stdout Buffer
stderr Buffer
Return: ChildProcess object
Runs a command in a shell and buffers the output.


var exec = require('child_process').exec,
touch <id>\r\n
    child;


child = exec('cat *.js bad_file | wc -l',
- <id> is the ID of a job reserved by the current connection.
  function (error, stdout, stderr) {
    console.log('stdout: ' + stdout);
    console.log('stderr: ' + stderr);
    if (error !== null) {
      console.log('exec error: ' + error);
    }
});
The callback gets the arguments (error, stdout, stderr). On success, error will be null. On error, error will be an instance of Error and err.code will be the exit code of the child process, and err.signal will be set to the signal that terminated the process.


There is a second optional argument to specify several options. The default options are
There are two possible responses:


{ encoding: 'utf8',
- "TOUCHED\r\n" to indicate success.
  timeout: 0,
  maxBuffer: 200*1024,
  killSignal: 'SIGTERM',
  cwd: null,
  env: null }
If timeout is greater than 0, then it will kill the child process if it runs longer than timeout milliseconds. The child process is killed with killSignal (default: 'SIGTERM'). maxBuffer specifies the largest amount of data allowed on stdout or stderr - if this value is exceeded then the child process is killed.


child_process.execFile(file, args, options, callback)#
- "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
file String The filename of the program to run
args Array List of string arguments
options Object
cwd String Current working directory of the child process
env Object Environment key-value pairs
encoding String (Default: 'utf8')
timeout Number (Default: 0)
maxBuffer Number (Default: 200*1024)
killSignal String (Default: 'SIGTERM')
callback Function called with the output when process terminates
error Error
stdout Buffer
stderr Buffer
Return: ChildProcess object
This is similar to child_process.exec() except it does not execute a subshell but rather the specified file directly. This makes it slightly leaner than child_process.exec. It has the same options.


child_process.fork(modulePath, [args], [options])#
The "watch" command adds the named tube to the watch list for the current
modulePath String The module to run in the child
connection. A reserve command will take a job from any of the tubes in the
args Array List of string arguments
watch list. For each new connection, the watch list initially consists of one
options Object
tube, named "default".
cwd String Current working directory of the child process
env Object Environment key-value pairs
encoding String (Default: 'utf8')
execPath String Executable used to create the child process
Return: ChildProcess object
This is a special case of the spawn() functionality for spawning Node processes. In addition to having all the methods in a normal ChildProcess instance, the returned object has a communication channel built-in. See child.send(message, [sendHandle]) for details.


By default the spawned Node process will have the stdout, stderr associated with the parent's. To change this behavior set the silent property in the options object to true.
watch <tube>\r\n


The child process does not automatically exit once it's done, you need to call process.exit() explicitly. This limitation may be lifted in the future.
- <tube> is a name at most 200 bytes. It specifies a tube to add to the watch
  list. If the tube doesn't exist, it will be created.


These child Nodes are still whole new instances of V8. Assume at least 30ms startup and 10mb memory for each new Node. That is, you cannot create many thousands of them.
The reply is:


The execPath property in the options object allows for a process to be created for the child rather than the current node executable. This should be done with care and by default will talk over the fd represented an environmental variable NODE_CHANNEL_FD on the child process. The input and output on this fd is expected to be line delimited JSON objects.
WATCHING <count>\r\n
 
- <count> is the integer number of tubes currently in the watch list.
 
The "ignore" command is for consumers. It removes the named tube from the
watch list for the current connection.
 
ignore <tube>\r\n
 
The reply is one of:
 
- "WATCHING <count>\r\n" to indicate success.
 
  - <count> is the integer number of tubes currently in the watch list.
 
- "NOT_IGNORED\r\n" if the client attempts to ignore the only tube in its
  watch list.
 
Other Commands
--------------
 
The peek commands let the client inspect a job in the system. There are four
variations. All but the first operate only on the currently used tube.
 
- "peek <id>\r\n" - return job <id>.
 
- "peek-ready\r\n" - return the next ready job.
 
- "peek-delayed\r\n" - return the delayed job with the shortest delay left.
 
- "peek-buried\r\n" - return the next job in the list of buried jobs.
 
There are two possible responses, either a single line:
 
- "NOT_FOUND\r\n" if the requested job doesn't exist or there are no jobs in
  the requested state.
 
Or a line followed by a chunk of data, if the command was successful:
 
FOUND <id> <bytes>\r\n
<data>\r\n
 
- <id> is the job id.
 
- <bytes> is an integer indicating the size of the job body, not including
  the trailing "\r\n".
 
- <data> is the job body -- a sequence of bytes of length <bytes> from the
  previous line.
 
The kick command applies only to the currently used tube. It moves jobs into
the ready queue. If there are any buried jobs, it will only kick buried jobs.
Otherwise it will kick delayed jobs. It looks like:
 
kick <bound>\r\n
 
- <bound> is an integer upper bound on the number of jobs to kick. The server
  will kick no more than <bound> jobs.
 
The response is of the form:
 
KICKED <count>\r\n
 
- <count> is an integer indicating the number of jobs actually kicked.
 
The kick-job command is a variant of kick that operates with a single job
identified by its job id. If the given job id exists and is in a buried or
delayed state, it will be moved to the ready queue of the the same tube where it
currently belongs. The syntax is:
 
kick-job <id>\r\n
 
- <id> is the job id to kick.
 
The response is one of:
 
- "NOT_FOUND\r\n" if the job does not exist or is not in a kickable state. This
  can also happen upon internal errors.
 
- "KICKED\r\n" when the operation succeeded.
 
The stats-job command gives statistical information about the specified job if
it exists. Its form is:
 
stats-job <id>\r\n
 
- <id> is a job id.
 
The response is one of:
 
- "NOT_FOUND\r\n" if the job does not exist.
 
- "OK <bytes>\r\n<data>\r\n"
 
  - <bytes> is the size of the following data section in bytes.
 
  - <data> is a sequence of bytes of length <bytes> from the previous line. It
    is a YAML file with statistical information represented a dictionary.
 
The stats-job data is a YAML file representing a single dictionary of strings
to scalars. It contains these keys:
 
- "id" is the job id
 
- "tube" is the name of the tube that contains this job
 
- "state" is "ready" or "delayed" or "reserved" or "buried"
 
- "pri" is the priority value set by the put, release, or bury commands.
 
- "age" is the time in seconds since the put command that created this job.
 
- "time-left" is the number of seconds left until the server puts this job
  into the ready queue. This number is only meaningful if the job is
  reserved or delayed. If the job is reserved and this amount of time
  elapses before its state changes, it is considered to have timed out.
 
- "file" is the number of the earliest binlog file containing this job.
  If -b wasn't used, this will be 0.
 
- "reserves" is the number of times this job has been reserved.
 
- "timeouts" is the number of times this job has timed out during a
  reservation.
 
- "releases" is the number of times a client has released this job from a
  reservation.
 
- "buries" is the number of times this job has been buried.
 
- "kicks" is the number of times this job has been kicked.
 
The stats-tube command gives statistical information about the specified tube
if it exists. Its form is:
 
stats-tube <tube>\r\n
 
- <tube> is a name at most 200 bytes. Stats will be returned for this tube.
 
The response is one of:
 
- "NOT_FOUND\r\n" if the tube does not exist.
 
- "OK <bytes>\r\n<data>\r\n"
 
  - <bytes> is the size of the following data section in bytes.
 
  - <data> is a sequence of bytes of length <bytes> from the previous line. It
    is a YAML file with statistical information represented a dictionary.
 
The stats-tube data is a YAML file representing a single dictionary of strings
to scalars. It contains these keys:
 
- "name" is the tube's name.
 
- "current-jobs-urgent" is the number of ready jobs with priority < 1024 in
  this tube.
 
- "current-jobs-ready" is the number of jobs in the ready queue in this tube.
 
- "current-jobs-reserved" is the number of jobs reserved by all clients in
  this tube.
 
- "current-jobs-delayed" is the number of delayed jobs in this tube.
 
- "current-jobs-buried" is the number of buried jobs in this tube.
 
- "total-jobs" is the cumulative count of jobs created in this tube in
  the current beanstalkd process.
 
- "current-using" is the number of open connections that are currently
  using this tube.
 
- "current-waiting" is the number of open connections that have issued a
  reserve command while watching this tube but not yet received a response.
 
- "current-watching" is the number of open connections that are currently
  watching this tube.
 
- "pause" is the number of seconds the tube has been paused for.
 
- "cmd-delete" is the cumulative number of delete commands for this tube
 
- "cmd-pause-tube" is the cumulative number of pause-tube commands for this
  tube.
 
- "pause-time-left" is the number of seconds until the tube is un-paused.
 
The stats command gives statistical information about the system as a whole.
Its form is:
 
stats\r\n
 
The server will respond:
 
OK <bytes>\r\n
<data>\r\n
 
- <bytes> is the size of the following data section in bytes.
 
- <data> is a sequence of bytes of length <bytes> from the previous line. It
  is a YAML file with statistical information represented a dictionary.
 
The stats data for the system is a YAML file representing a single dictionary
of strings to scalars. Entries described as "cumulative" are reset when the
beanstalkd process starts; they are not stored on disk with the -b flag.
 
- "current-jobs-urgent" is the number of ready jobs with priority < 1024.
 
- "current-jobs-ready" is the number of jobs in the ready queue.
 
- "current-jobs-reserved" is the number of jobs reserved by all clients.
 
- "current-jobs-delayed" is the number of delayed jobs.
 
- "current-jobs-buried" is the number of buried jobs.
 
- "cmd-put" is the cumulative number of put commands.
 
- "cmd-peek" is the cumulative number of peek commands.
 
- "cmd-peek-ready" is the cumulative number of peek-ready commands.
 
- "cmd-peek-delayed" is the cumulative number of peek-delayed commands.
 
- "cmd-peek-buried" is the cumulative number of peek-buried commands.
 
- "cmd-reserve" is the cumulative number of reserve commands.
 
- "cmd-use" is the cumulative number of use commands.
 
- "cmd-watch" is the cumulative number of watch commands.
 
- "cmd-ignore" is the cumulative number of ignore commands.
 
- "cmd-delete" is the cumulative number of delete commands.
 
- "cmd-release" is the cumulative number of release commands.
 
- "cmd-bury" is the cumulative number of bury commands.
 
- "cmd-kick" is the cumulative number of kick commands.
 
- "cmd-stats" is the cumulative number of stats commands.
 
- "cmd-stats-job" is the cumulative number of stats-job commands.
 
- "cmd-stats-tube" is the cumulative number of stats-tube commands.
 
- "cmd-list-tubes" is the cumulative number of list-tubes commands.
 
- "cmd-list-tube-used" is the cumulative number of list-tube-used commands.
 
- "cmd-list-tubes-watched" is the cumulative number of list-tubes-watched
  commands.
 
- "cmd-pause-tube" is the cumulative number of pause-tube commands.
 
- "job-timeouts" is the cumulative count of times a job has timed out.
 
- "total-jobs" is the cumulative count of jobs created.
 
- "max-job-size" is the maximum number of bytes in a job.
 
- "current-tubes" is the number of currently-existing tubes.
 
- "current-connections" is the number of currently open connections.
 
- "current-producers" is the number of open connections that have each
  issued at least one put command.
 
- "current-workers" is the number of open connections that have each issued
  at least one reserve command.
 
- "current-waiting" is the number of open connections that have issued a
  reserve command but not yet received a response.
 
- "total-connections" is the cumulative count of connections.
 
- "pid" is the process id of the server.
 
- "version" is the version string of the server.
 
- "rusage-utime" is the cumulative user CPU time of this process in seconds
  and microseconds.
 
- "rusage-stime" is the cumulative system CPU time of this process in
  seconds and microseconds.
 
- "uptime" is the number of seconds since this server process started running.
 
- "binlog-oldest-index" is the index of the oldest binlog file needed to
  store the current jobs.
 
- "binlog-current-index" is the index of the current binlog file being
  written to. If binlog is not active this value will be 0.
 
- "binlog-max-size" is the maximum size in bytes a binlog file is allowed
  to get before a new binlog file is opened.
 
- "binlog-records-written" is the cumulative number of records written
  to the binlog.
 
- "binlog-records-migrated" is the cumulative number of records written
  as part of compaction.
 
- "id" is a random id string for this server process, generated when each
  beanstalkd process starts.
 
- "hostname" the hostname of the machine as determined by uname.
 
The list-tubes command returns a list of all existing tubes. Its form is:
 
list-tubes\r\n
 
The response is:
 
OK <bytes>\r\n
<data>\r\n
 
- <bytes> is the size of the following data section in bytes.
 
- <data> is a sequence of bytes of length <bytes> from the previous line. It
  is a YAML file containing all tube names as a list of strings.
 
The list-tube-used command returns the tube currently being used by the
client. Its form is:
 
list-tube-used\r\n
 
The response is:
 
USING <tube>\r\n
 
- <tube> is the name of the tube being used.
 
The list-tubes-watched command returns a list tubes currently being watched by
the client. Its form is:
 
list-tubes-watched\r\n
 
The response is:
 
OK <bytes>\r\n
<data>\r\n
 
- <bytes> is the size of the following data section in bytes.
 
- <data> is a sequence of bytes of length <bytes> from the previous line. It
  is a YAML file containing watched tube names as a list of strings.
 
The quit command simply closes the connection. Its form is:
 
quit\r\n
 
The pause-tube command can delay any new job being reserved for a given time. Its form is:
 
pause-tube <tube-name> <delay>\r\n
 
- <tube> is the tube to pause
 
- <delay> is an integer number of seconds to wait before reserving any more
  jobs from the queue
 
There are two possible responses:
 
- "PAUSED\r\n" to indicate success.
 
- "NOT_FOUND\r\n" if the tube does not exist.

Версия от 08:14, 8 мая 2014

Beanstalk Protocol

Protocol

The beanstalk protocol runs over TCP using ASCII encoding. Clients connect, send commands and data, wait for responses, and close the connection. For each connection, the server processes commands serially in the order in which they were received and sends responses in the same order. All integers in the protocol are formatted in decimal and (unless otherwise indicated) nonnegative.

Names, in this protocol, are ASCII strings. They may contain letters (A-Z and a-z), numerals (0-9), hyphen ("-"), plus ("+"), slash ("/"), semicolon (";"), dot ("."), dollar-sign ("$"), underscore ("_"), and parentheses ("(" and ")"), but they may not begin with a hyphen. They are terminated by white space (either a space char or end of line). Each name must be at least one character long.

The protocol contains two kinds of data: text lines and unstructured chunks of data. Text lines are used for client commands and server responses. Chunks are used to transfer job bodies and stats information. Each job body is an opaque sequence of bytes. The server never inspects or modifies a job body and always sends it back in its original form. It is up to the clients to agree on a meaningful interpretation of job bodies.

The client may issue the "quit" command, or simply close the TCP connection when it no longer has use for the server. However, beanstalkd performs very well with a large number of open connections, so it is usually better for the client to keep its connection open and reuse it as much as possible. This also avoids the overhead of establishing new TCP connections.

If a client violates the protocol (such as by sending a request that is not well-formed or a command that does not exist) or if the server has an error, the server will reply with one of the following error messages: 

- "OUT_OF_MEMORY\r\n" The server cannot allocate enough memory for the job.
  The client should try again later.

- "INTERNAL_ERROR\r\n" This indicates a bug in the server. It should never
  happen. If it does happen, please report it at
  http://groups.google.com/group/beanstalk-talk.

- "BAD_FORMAT\r\n" The client sent a command line that was not well-formed.
  This can happen if the line does not end with \r\n, if non-numeric
  characters occur where an integer is expected, if the wrong number of
  arguments are present, or if the command line is mal-formed in any other
  way.

- "UNKNOWN_COMMAND\r\n" The client sent a command that the server does not
  know.

These error responses will not be listed in this document for individual commands in the following sections, but they are implicitly included in the description of all commands. Clients should be prepared to receive an error response after any command.

As a last resort, if the server has a serious error that prevents it from continuing service to the current client, the server will close the connection.

Job Lifecycle

A job in beanstalk gets created by a client with the "put" command. During its life it can be in one of four states: "ready", "reserved", "delayed", or "buried". After the put command, a job typically starts out ready. It waits in the ready queue until a worker comes along and runs the "reserve" command. If this job is next in the queue, it will be reserved for the worker. The worker will execute the job; when it is finished the worker will send a "delete" command to delete the job.

Here is a picture of the typical job lifecycle: 


  put            reserve               delete
 -----> [READY] ---------> [RESERVED] --------> *poof*


Here is a picture with more possibilities: 


  put with delay               release with delay
 ----------------> [DELAYED] <------------.
                       |                   |
                       | (time passes)     |
                       |                   |
  put                  v     reserve       |       delete
 -----------------> [READY] ---------> [RESERVED] --------> *poof*
                      ^  ^                |  |
                      |   \  release      |  |
                      |    `-------------'   |
                      |                      |
                      | kick                 |
                      |                      |
                      |       bury           |
                   [BURIED] <---------------'
                      |
                      |  delete
                       `--------> *poof*


The system has one or more tubes. Each tube consists of a ready queue and a delay queue. Each job spends its entire life in one tube. Consumers can show interest in tubes by sending the "watch" command; they can show disinterest by sending the "ignore" command. This set of interesting tubes is said to be a consumer's "watch list". When a client reserves a job, it may come from any of the tubes in its watch list.

When a client connects, its watch list is initially just the tube named "default". If it submits jobs without having sent a "use" command, they will live in the tube named "default".

Tubes are created on demand whenever they are referenced. If a tube is empty (that is, it contains no ready, delayed, or buried jobs) and no client refers to it, it will be deleted.

Producer Commands

The "put" command is for any process that wants to insert a job into the queue. It comprises a command line followed by the job body:

put <pri> <delay> <ttr> <bytes>\r\n \r\n

It inserts a job into the client's currently used tube (see the "use" command below). 

- <pri> is an integer < 2**32. Jobs with smaller priority values will be
  scheduled before jobs with larger priorities. The most urgent priority is 0;
  the least urgent priority is 4,294,967,295.

- <delay> is an integer number of seconds to wait before putting the job in
  the ready queue. The job will be in the "delayed" state during this time.

- <ttr> -- time to run -- is an integer number of seconds to allow a worker
  to run this job. This time is counted from the moment a worker reserves
  this job. If the worker does not delete, release, or bury the job within
  <ttr> seconds, the job will time out and the server will release the job.
  The minimum ttr is 1. If the client sends 0, the server will silently
  increase the ttr to 1.

- <bytes> is an integer indicating the size of the job body, not including the
  trailing "\r\n". This value must be less than max-job-size (default: 2**16).

-  is the job body -- a sequence of bytes of length <bytes> from the
  previous line.

After sending the command line and body, the client waits for a reply, which may be: 

- "INSERTED <id>\r\n" to indicate success.

  - <id> is the integer id of the new job

- "BURIED <id>\r\n" if the server ran out of memory trying to grow the
  priority queue data structure.

  - <id> is the integer id of the new job

- "EXPECTED_CRLF\r\n" The job body must be followed by a CR-LF pair, that is,
  "\r\n". These two bytes are not counted in the job size given by the client
  in the put command line.

- "JOB_TOO_BIG\r\n" The client has requested to put a job with a body larger
  than max-job-size bytes.

- "DRAINING\r\n" This means that the server has been put into "drain mode"
  and is no longer accepting new jobs. The client should try another server
  or disconnect and try again later.

The "use" command is for producers. Subsequent put commands will put jobs into the tube specified by this command. If no use command has been issued, jobs will be put into the tube named "default".

use <tube>\r\n 

- <tube> is a name at most 200 bytes. It specifies the tube to use. If the
  tube does not exist, it will be created.

The only reply is:

USING <tube>\r\n 

- <tube> is the name of the tube now being used.

Worker Commands

A process that wants to consume jobs from the queue uses "reserve", "delete", "release", and "bury". The first worker command, "reserve", looks like this:

reserve\r\n

Alternatively, you can specify a timeout as follows:

reserve-with-timeout <seconds>\r\n

This will return a newly-reserved job. If no job is available to be reserved, beanstalkd will wait to send a response until one becomes available. Once a job is reserved for the client, the client has limited time to run (TTR) the job before the job times out. When the job times out, the server will put the job back into the ready queue. Both the TTR and the actual time left can be found in response to the stats-job command.

If more than one job is ready, beanstalkd will choose the one with the smallest priority value. Within each priority, it will choose the one that was received first.

A timeout value of 0 will cause the server to immediately return either a response or TIMED_OUT. A positive value of timeout will limit the amount of time the client will block on the reserve request until a job becomes available.

During the TTR of a reserved job, the last second is kept by the server as a safety margin, during which the client will not be made to wait for another job. If the client issues a reserve command during the safety margin, or if the safety margin arrives while the client is waiting on a reserve command, the server will respond with:

DEADLINE_SOON\r\n

This gives the client a chance to delete or release its reserved job before the server automatically releases it.

TIMED_OUT\r\n

If a non-negative timeout was specified and the timeout exceeded before a job became available, or if the client's connection is half-closed, the server will respond with TIMED_OUT.

Otherwise, the only other response to this command is a successful reservation in the form of a text line followed by the job body:

RESERVED <id> <bytes>\r\n \r\n 

- <id> is the job id -- an integer unique to this job in this instance of
  beanstalkd.

- <bytes> is an integer indicating the size of the job body, not including
  the trailing "\r\n".

-  is the job body -- a sequence of bytes of length <bytes> from the
  previous line. This is a verbatim copy of the bytes that were originally
  sent to the server in the put command for this job.

The delete command removes a job from the server entirely. It is normally used by the client when the job has successfully run to completion. A client can delete jobs that it has reserved, ready jobs, delayed jobs, and jobs that are buried. The delete command looks like this:

delete <id>\r\n 

- <id> is the job id to delete.

The client then waits for one line of response, which may be: 

- "DELETED\r\n" to indicate success.

- "NOT_FOUND\r\n" if the job does not exist or is not either reserved by the
  client, ready, or buried. This could happen if the job timed out before the
  client sent the delete command.

The release command puts a reserved job back into the ready queue (and marks its state as "ready") to be run by any client. It is normally used when the job fails because of a transitory error. It looks like this:

release <id> <pri> <delay>\r\n 

- <id> is the job id to release.

- <pri> is a new priority to assign to the job.

- <delay> is an integer number of seconds to wait before putting the job in
  the ready queue. The job will be in the "delayed" state during this time.

The client expects one line of response, which may be: 

- "RELEASED\r\n" to indicate success.

- "BURIED\r\n" if the server ran out of memory trying to grow the priority
  queue data structure.

- "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.

The bury command puts a job into the "buried" state. Buried jobs are put into a FIFO linked list and will not be touched by the server again until a client kicks them with the "kick" command.

The bury command looks like this:

bury <id> <pri>\r\n 

- <id> is the job id to release.

- <pri> is a new priority to assign to the job.

There are two possible responses: 

- "BURIED\r\n" to indicate success.

- "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.

The "touch" command allows a worker to request more time to work on a job. This is useful for jobs that potentially take a long time, but you still want the benefits of a TTR pulling a job away from an unresponsive worker. A worker may periodically tell the server that it's still alive and processing a job (e.g. it may do this on DEADLINE_SOON). The command postpones the auto release of a reserved job until TTR seconds from when the command is issued.

The touch command looks like this:

touch <id>\r\n 

- <id> is the ID of a job reserved by the current connection.

There are two possible responses: 

- "TOUCHED\r\n" to indicate success.

- "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.

The "watch" command adds the named tube to the watch list for the current connection. A reserve command will take a job from any of the tubes in the watch list. For each new connection, the watch list initially consists of one tube, named "default".

watch <tube>\r\n 

- <tube> is a name at most 200 bytes. It specifies a tube to add to the watch
  list. If the tube doesn't exist, it will be created.

The reply is:

WATCHING <count>\r\n 

- <count> is the integer number of tubes currently in the watch list.

The "ignore" command is for consumers. It removes the named tube from the watch list for the current connection.

ignore <tube>\r\n

The reply is one of: 

- "WATCHING <count>\r\n" to indicate success.

  - <count> is the integer number of tubes currently in the watch list.

- "NOT_IGNORED\r\n" if the client attempts to ignore the only tube in its
  watch list.

Other Commands

The peek commands let the client inspect a job in the system. There are four variations. All but the first operate only on the currently used tube. 

- "peek <id>\r\n" - return job <id>.

- "peek-ready\r\n" - return the next ready job.

- "peek-delayed\r\n" - return the delayed job with the shortest delay left.

- "peek-buried\r\n" - return the next job in the list of buried jobs.

There are two possible responses, either a single line: 

- "NOT_FOUND\r\n" if the requested job doesn't exist or there are no jobs in
  the requested state.

Or a line followed by a chunk of data, if the command was successful:

FOUND <id> <bytes>\r\n \r\n 

- <id> is the job id.

- <bytes> is an integer indicating the size of the job body, not including
  the trailing "\r\n".

-  is the job body -- a sequence of bytes of length <bytes> from the
  previous line.

The kick command applies only to the currently used tube. It moves jobs into the ready queue. If there are any buried jobs, it will only kick buried jobs. Otherwise it will kick delayed jobs. It looks like:

kick <bound>\r\n 

- <bound> is an integer upper bound on the number of jobs to kick. The server
  will kick no more than <bound> jobs.

The response is of the form:

KICKED <count>\r\n 

- <count> is an integer indicating the number of jobs actually kicked.

The kick-job command is a variant of kick that operates with a single job identified by its job id. If the given job id exists and is in a buried or delayed state, it will be moved to the ready queue of the the same tube where it currently belongs. The syntax is:

kick-job <id>\r\n 

- <id> is the job id to kick.

The response is one of: 

- "NOT_FOUND\r\n" if the job does not exist or is not in a kickable state. This
  can also happen upon internal errors.

- "KICKED\r\n" when the operation succeeded.

The stats-job command gives statistical information about the specified job if it exists. Its form is:

stats-job <id>\r\n 

- <id> is a job id.

The response is one of: 

- "NOT_FOUND\r\n" if the job does not exist.

- "OK <bytes>\r\n\r\n"

  - <bytes> is the size of the following data section in bytes.

  -  is a sequence of bytes of length <bytes> from the previous line. It
    is a YAML file with statistical information represented a dictionary.

The stats-job data is a YAML file representing a single dictionary of strings to scalars. It contains these keys: 

- "id" is the job id

- "tube" is the name of the tube that contains this job

- "state" is "ready" or "delayed" or "reserved" or "buried"

- "pri" is the priority value set by the put, release, or bury commands.

- "age" is the time in seconds since the put command that created this job.

- "time-left" is the number of seconds left until the server puts this job
  into the ready queue. This number is only meaningful if the job is
  reserved or delayed. If the job is reserved and this amount of time
  elapses before its state changes, it is considered to have timed out.

- "file" is the number of the earliest binlog file containing this job.
  If -b wasn't used, this will be 0.

- "reserves" is the number of times this job has been reserved.

- "timeouts" is the number of times this job has timed out during a
  reservation.

- "releases" is the number of times a client has released this job from a
  reservation.

- "buries" is the number of times this job has been buried.

- "kicks" is the number of times this job has been kicked.

The stats-tube command gives statistical information about the specified tube if it exists. Its form is:

stats-tube <tube>\r\n 

- <tube> is a name at most 200 bytes. Stats will be returned for this tube.

The response is one of: 

- "NOT_FOUND\r\n" if the tube does not exist.

- "OK <bytes>\r\n\r\n"

  - <bytes> is the size of the following data section in bytes.

  -  is a sequence of bytes of length <bytes> from the previous line. It
    is a YAML file with statistical information represented a dictionary.

The stats-tube data is a YAML file representing a single dictionary of strings to scalars. It contains these keys: 

- "name" is the tube's name.

- "current-jobs-urgent" is the number of ready jobs with priority < 1024 in
  this tube.

- "current-jobs-ready" is the number of jobs in the ready queue in this tube.

- "current-jobs-reserved" is the number of jobs reserved by all clients in
  this tube.

- "current-jobs-delayed" is the number of delayed jobs in this tube.

- "current-jobs-buried" is the number of buried jobs in this tube.

- "total-jobs" is the cumulative count of jobs created in this tube in
  the current beanstalkd process.

- "current-using" is the number of open connections that are currently
  using this tube.

- "current-waiting" is the number of open connections that have issued a
  reserve command while watching this tube but not yet received a response.

- "current-watching" is the number of open connections that are currently
  watching this tube.

- "pause" is the number of seconds the tube has been paused for.

- "cmd-delete" is the cumulative number of delete commands for this tube

- "cmd-pause-tube" is the cumulative number of pause-tube commands for this
  tube.

- "pause-time-left" is the number of seconds until the tube is un-paused.

The stats command gives statistical information about the system as a whole. Its form is:

stats\r\n

The server will respond:

OK <bytes>\r\n \r\n 

- <bytes> is the size of the following data section in bytes.

-  is a sequence of bytes of length <bytes> from the previous line. It
  is a YAML file with statistical information represented a dictionary.

The stats data for the system is a YAML file representing a single dictionary of strings to scalars. Entries described as "cumulative" are reset when the beanstalkd process starts; they are not stored on disk with the -b flag. 

- "current-jobs-urgent" is the number of ready jobs with priority < 1024.

- "current-jobs-ready" is the number of jobs in the ready queue.

- "current-jobs-reserved" is the number of jobs reserved by all clients.

- "current-jobs-delayed" is the number of delayed jobs.

- "current-jobs-buried" is the number of buried jobs.

- "cmd-put" is the cumulative number of put commands.

- "cmd-peek" is the cumulative number of peek commands.

- "cmd-peek-ready" is the cumulative number of peek-ready commands.

- "cmd-peek-delayed" is the cumulative number of peek-delayed commands.

- "cmd-peek-buried" is the cumulative number of peek-buried commands.

- "cmd-reserve" is the cumulative number of reserve commands.

- "cmd-use" is the cumulative number of use commands.

- "cmd-watch" is the cumulative number of watch commands.

- "cmd-ignore" is the cumulative number of ignore commands.

- "cmd-delete" is the cumulative number of delete commands.

- "cmd-release" is the cumulative number of release commands.

- "cmd-bury" is the cumulative number of bury commands.

- "cmd-kick" is the cumulative number of kick commands.

- "cmd-stats" is the cumulative number of stats commands.

- "cmd-stats-job" is the cumulative number of stats-job commands.

- "cmd-stats-tube" is the cumulative number of stats-tube commands.

- "cmd-list-tubes" is the cumulative number of list-tubes commands.

- "cmd-list-tube-used" is the cumulative number of list-tube-used commands.

- "cmd-list-tubes-watched" is the cumulative number of list-tubes-watched
  commands.

- "cmd-pause-tube" is the cumulative number of pause-tube commands.

- "job-timeouts" is the cumulative count of times a job has timed out.

- "total-jobs" is the cumulative count of jobs created.

- "max-job-size" is the maximum number of bytes in a job.

- "current-tubes" is the number of currently-existing tubes.

- "current-connections" is the number of currently open connections.

- "current-producers" is the number of open connections that have each
  issued at least one put command.

- "current-workers" is the number of open connections that have each issued
  at least one reserve command.

- "current-waiting" is the number of open connections that have issued a
  reserve command but not yet received a response.

- "total-connections" is the cumulative count of connections.

- "pid" is the process id of the server.

- "version" is the version string of the server.

- "rusage-utime" is the cumulative user CPU time of this process in seconds
  and microseconds.

- "rusage-stime" is the cumulative system CPU time of this process in
  seconds and microseconds.

- "uptime" is the number of seconds since this server process started running.

- "binlog-oldest-index" is the index of the oldest binlog file needed to
  store the current jobs.

- "binlog-current-index" is the index of the current binlog file being
  written to. If binlog is not active this value will be 0.

- "binlog-max-size" is the maximum size in bytes a binlog file is allowed
  to get before a new binlog file is opened.

- "binlog-records-written" is the cumulative number of records written
  to the binlog.

- "binlog-records-migrated" is the cumulative number of records written
  as part of compaction.

- "id" is a random id string for this server process, generated when each
  beanstalkd process starts.

- "hostname" the hostname of the machine as determined by uname.

The list-tubes command returns a list of all existing tubes. Its form is:

list-tubes\r\n

The response is:

OK <bytes>\r\n \r\n 

- <bytes> is the size of the following data section in bytes.

-  is a sequence of bytes of length <bytes> from the previous line. It
  is a YAML file containing all tube names as a list of strings.

The list-tube-used command returns the tube currently being used by the client. Its form is:

list-tube-used\r\n

The response is:

USING <tube>\r\n 

- <tube> is the name of the tube being used.

The list-tubes-watched command returns a list tubes currently being watched by the client. Its form is:

list-tubes-watched\r\n

The response is:

OK <bytes>\r\n \r\n 

- <bytes> is the size of the following data section in bytes.

-  is a sequence of bytes of length <bytes> from the previous line. It
  is a YAML file containing watched tube names as a list of strings.

The quit command simply closes the connection. Its form is:

quit\r\n

The pause-tube command can delay any new job being reserved for a given time. Its form is:

pause-tube <tube-name> <delay>\r\n 

- <tube> is the tube to pause

- <delay> is an integer number of seconds to wait before reserving any more
  jobs from the queue

There are two possible responses: 

- "PAUSED\r\n" to indicate success.

- "NOT_FOUND\r\n" if the tube does not exist.
Источник — https://support.qbpro.ru/index.php?title=Child_Process&oldid=1434