libczmq-dev 4.1.0-2 / usr / share / zproject / czmq / zproc.api

<class name = "zproc" state = "draft">
    <!--
    Copyright (c) the Contributors as noted in the AUTHORS file.
    This file is part of CZMQ, the high-level C binding for 0MQ:
    http://czmq.zeromq.org.

    This Source Code Form is subject to the terms of the Mozilla Public
    License, v. 2.0. If a copy of the MPL was not distributed with this
    file, You can obtain one at http://mozilla.org/MPL/2.0/.
    -->
    process configuration and status

    <constructor>
        Create a new zproc.
        NOTE: On Windows and with libzmq3 and libzmq2 this function
        returns NULL. Code needs to be ported there.
    </constructor>

    <destructor>
        Destroy zproc, wait until process ends.
    </destructor>

    <method name = "set args" >
        Setup the command line arguments, the first item must be an (absolute) filename
        to run.
        <argument name = "args" type = "zlistx" />
    </method>

    <method name = "set env" >
        Setup the environment variables for the process.
        <argument name = "args" type = "zhashx" />
    </method>

    <method name = "set stdin" >
        Connects process stdin with a readable ('>', connect) zeromq socket. If
        socket argument is NULL, zproc creates own managed pair of inproc
        sockets.  The writable one is then accessbile via zproc_stdin method.
        <argument name = "socket" type = "anything" />
    </method>

    <method name = "set stdout" >
        Connects process stdout with a writable ('@', bind) zeromq socket. If
        socket argument is NULL, zproc creates own managed pair of inproc
        sockets.  The readable one is then accessbile via zproc_stdout method.
        <argument name = "socket" type = "anything" />
    </method>

    <method name = "set stderr" >
        Connects process stderr with a writable ('@', bind) zeromq socket. If
        socket argument is NULL, zproc creates own managed pair of inproc
        sockets.  The readable one is then accessbile via zproc_stderr method.
        <argument name = "socket" type = "anything" />
    </method>

    <method name = "stdin">
        Return subprocess stdin writable socket. NULL for
        not initialized or external sockets.
        <return type="anything" />
    </method>

    <method name = "stdout">
        Return subprocess stdout readable socket. NULL for
        not initialized or external sockets.
        <return type="anything" />
    </method>

    <method name = "stderr">
        Return subprocess stderr readable socket. NULL for
        not initialized or external sockets.
        <return type="anything" />
    </method>

    <method name = "run" >
        Starts the process.
        <return type = "integer" />
    </method>

    <method name = "returncode">
        process exit code
        <return type="integer" />
    </method>

    <method name = "pid">
        PID of the process
        <return type="integer" />
    </method>

    <method name = "running">
        return true if process is running, false if not yet started or finished
        <return type="boolean" />
    </method>

    <method name = "wait">
        wait or poll process status, return return code
        <argument name = "hang" type = "boolean" />
        <return type="integer" />
    </method>

    <method name = "actor">
        return internal actor, usefull for the polling if process died
        <return type="anything" />
    </method>

    <method name = "kill">
        send a signal to the subprocess
        <argument name = "signal" type = "integer" />
    </method>

    <method name = "set verbose">
        set verbose mode
        <argument name = "verbose" type = "boolean" />
    </method>

<!--
TODO: cannot express such method in zproto API model!!
//  run the subprocess
CZMQ_EXPORT int
    zsubproc_run (zsubproc_t *self, const char *filename, char *const argv[], char *const envp[]);
-->

    <method name = "czmq version" singleton = "1">
        Returns CZMQ version as a single 6-digit integer encoding the major
        version (x 10000), the minor version (x 100) and the patch.
        <return type = "integer" />
    </method>

    <method name = "interrupted" singleton = "1">
        Returns true if the process received a SIGINT or SIGTERM signal.
        It is good practice to use this method to exit any infinite loop
        processing messages.
        <return type = "boolean" />
    </method>

    <method name = "has curve" singleton = "1">
        Returns true if the underlying libzmq supports CURVE security.
        <return type = "boolean" />
    </method>

    <method name = "hostname" singleton = "1">
        Return current host name, for use in public tcp:// endpoints.
        If the host name is not resolvable, returns NULL.
        <return type = "string" fresh = "1" />
    </method>

    <method name = "daemonize" singleton = "1">
        Move the current process into the background. The precise effect
        depends on the operating system. On POSIX boxes, moves to a specified
        working directory (if specified), closes all file handles, reopens
        stdin, stdout, and stderr to the null device, and sets the process to
        ignore SIGHUP. On Windows, does nothing. Returns 0 if OK, -1 if there
        was an error.
        <argument name = "workdir" type = "string" />
    </method>

    <method name = "run as" singleton = "1">
        Drop the process ID into the lockfile, with exclusive lock, and
        switch the process to the specified group and/or user. Any of the
        arguments may be null, indicating a no-op. Returns 0 on success,
        -1 on failure. Note if you combine this with zsys_daemonize, run
        after, not before that method, or the lockfile will hold the wrong
        process ID.
        <argument name = "lockfile" type = "string" />
        <argument name = "group" type = "string" />
        <argument name = "user" type = "string" />
    </method>

    <method name = "set io threads" singleton = "1">
        Configure the number of I/O threads that ZeroMQ will use. A good
        rule of thumb is one thread per gigabit of traffic in or out. The
        default is 1, sufficient for most applications. If the environment
        variable ZSYS_IO_THREADS is defined, that provides the default.
        Note that this method is valid only before any socket is created.
        <argument name = "io_threads" type = "size" />
    </method>

    <method name = "set max sockets" singleton = "1">
        Configure the number of sockets that ZeroMQ will allow. The default
        is 1024. The actual limit depends on the system, and you can query it
        by using zsys_socket_limit (). A value of zero means "maximum".
        Note that this method is valid only before any socket is created.
        <argument name = "max_sockets" type = "size" />
    </method>

    <method name = "set biface" singleton = "1">
        Set network interface name to use for broadcasts, particularly zbeacon.
        This lets the interface be configured for test environments where required.
        For example, on Mac OS X, zbeacon cannot bind to 255.255.255.255 which is
        the default when there is no specified interface. If the environment
        variable ZSYS_INTERFACE is set, use that as the default interface name.
        Setting the interface to "*" means "use all available interfaces".
        <argument name = "value" type = "string" />
    </method>

    <method name = "biface" singleton = "1">
        Return network interface to use for broadcasts, or "" if none was set.
        <return type = "string" />
    </method>

    <method name = "set log ident" singleton = "1">
        Set log identity, which is a string that prefixes all log messages sent
        by this process. The log identity defaults to the environment variable
        ZSYS_LOGIDENT, if that is set.
        <argument name = "value" type = "string" />
    </method>

    <method name = "set log sender" singleton = "1">
        Sends log output to a PUB socket bound to the specified endpoint. To
        collect such log output, create a SUB socket, subscribe to the traffic
        you care about, and connect to the endpoint. Log traffic is sent as a
        single string frame, in the same format as when sent to stdout. The
        log system supports a single sender; multiple calls to this method will
        bind the same sender to multiple endpoints. To disable the sender, call
        this method with a null argument.
        <argument name = "endpoint" type = "string" />
    </method>

    <method name = "set log system" singleton = "1">
        Enable or disable logging to the system facility (syslog on POSIX boxes,
        event log on Windows). By default this is disabled.
        <argument name = "logsystem" type = "boolean" />
    </method>

    <method name = "log error" singleton = "1">
        Log error condition - highest priority
        <argument name = "format" type = "format" />
    </method>

    <method name = "log warning" singleton = "1">
        Log warning condition - high priority
        <argument name = "format" type = "format" />
    </method>

    <method name = "log notice" singleton = "1">
        Log normal, but significant, condition - normal priority
        <argument name = "format" type = "format" />
    </method>

    <method name = "log info" singleton = "1">
        Log informational message - low priority
        <argument name = "format" type = "format" />
    </method>

    <method name = "log debug" singleton = "1">
        Log debug-level message - lowest priority
        <argument name = "format" type = "format" />
    </method>
</class>