Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::G::SpawnAsync Class Reference

A C++ interface for the GLib asynchronous spawn functions. More...

`#include <inti/glib/spawn.h>`

Inheritance diagram for Inti::G::SpawnAsync:

List of all members.

## Public Member Functions

Constructors

- SpawnAsync (const std::vector< std::string > &argv, SpawnFlagsField flags=0)
    Constructs an asynchronous spawn object with the specified arguments argv and spawn flags.
- SpawnAsync (const std::string &command_line, G::Error *error)
    Constructs an asynchronous spawn object with the specified arguments in the command_line string.
- ~SpawnAsync ()
    Destructor.

Accessors

- int process_id () const
    Returns the child process ID or zero if an error occurs.

Methods

- bool execute (G::Error *error, const ChildSetupSlot *slot=0)
    Executes a child program asynchronously (that is, your program will not block waiting for the child to exit).
- void set_standard_input (int &standard_input)
    Sets the return location for a file descriptor to write to child's stdin.
- void set_standard_output (int &standard_output)
    Sets the return location for a file descriptor to read child's stdout.
- void set_standard_error (int &standard_error)
    Sets the return location for a file descriptor to read child's stderr.

## Detailed Description

A C++ interface for the GLib asynchronous spawn functions.

SpawnAsync executes a child program asynchronously (that is, your program will not block waiting for the child to exit). The child program is specified by the only argument that must be provided, argv. argv should be a vector of std::strings, to be passed as the argument vector for the child. The first string in argv is of course the name of the program to execute. By default, the name of the program must be a full path; the PATH shell variable will only be searched if you pass the G::SPAWN_SEARCH_PATH flag. The first constructor takes an argv as a parameter and one or more optional spawn flags. The second constructor creates the argv argument for you from the passed in command line.

SpawnFlagsField should be the bitwise OR of any flags you want to affect the child's behavior. On Unix, the G::SPAWN_DO_NOT_REAP_CHILD means that the child will not be automatically reaped; you must call waitpid() or handle SIGCHLD yourself, or the child will become a zombie. On Windows, the flag means that a handle to the child will be returned child_pid. You must call CloseHandle() on it eventually (or exit the process), or the child processs will continue to take up some table space even after its death. Quite similar to zombies on Unix, actually.

G::SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file descriptors will be inherited by the child; otherwise all descriptors except stdin/stdout/stderr will be closed before calling exec() in the child. G::SPAWN_SEARCH_PATH means that argv[0] need not be an absolute path, it will be looked for in the user's PATH. G::SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output will be discarded, instead of going to the same location as the parent's standard output. If you use this flag, set_standard_output() is ignored. G::SPAWN_STDERR_TO_DEV_NULL means that the child's standard error will be discarded, instead of going to the same location as the parent's standard error. If you use this flag, set_standard_error() will be ignored. G::SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's standard input (by default, the child's standard input is attached to /dev/null). If you use this flag, set_standard_input() will be ignored. G::SPAWN_FILE_AND_ARGV_ZERO means that the first element of argv is the file to execute, while the remaining elements are the actual argument vector to pass to the file. Normally SpawnAsync uses argv[0] as the file to execute, and passes all of argv to the child.

ChildSetupSlot is a user-defined method. On POSIX platforms, the method is called in the child after GLib has performed all the setup it plans to perform (including creating pipes, closing file descriptors, etc.) but before calling exec(). That is, the ChildSetupSlot is called just before calling exec() in the child. Obviously actions taken in this method will only affect the child, not the parent. On Windows, there is no separate fork() and exec() functionality. Child processes are created and run right away with one API call, CreateProcess(). The ChildSetupSlot is called in the parent process just before creating the child process. You should carefully consider what you do in the ChildSetupSlot method if you intend your software to be portable to Windows.

The process_id() method returns the child's process ID. You can use the process ID to send signals to the child, or to waitpid() if you specified the G::SPAWN_DO_NOT_REAP_CHILD flag. On Windows, child_pid will be filled with a handle to the child process only if you specified the G::SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child process using the Win32 API, for example wait for its termination with the WaitFor*() functions, or examine its exit code with GetExitCodeProcess(). You should close the handle with CloseHandle() when you no longer need it.

The set_standard_input(), set_standard_output() and set_standard_error() methods take a reference to an int whose value is set to a file descriptor when execute() returns. The file descriptors are used for writing to the child's standard input or reading from its standard output or standard error, and must be closed by calling close() when no longer required.

If set_standard_input() is not called the child's standard input is attached to /dev/null unless G::SPAWN_CHILD_INHERITS_STDIN is set. If set_standard_error() is not called the child's standard error goes to the same location as the parent's standard error unless G::SPAWN_STDERR_TO_DEV_NULL is set. If set_standard_output() is not called the child's standard output goes to the same location as the parent's standard output unless G::SPAWN_STDOUT_TO_DEV_NULL is set.

A G::Error should be passed to execute() to report errors but can be null to ignore them. If the G::Error is set, execute() returns false. Errors are reported even if they occur in the child (for example if the executable in argv[0] is not found). Typically the message field of returned errors should be displayed to users. Possible errors are those from the G_SPAWN_ERROR domain. If an error occurs the standard_input, standard_output, and standard_error file descriptors will not be filled with valid values, and process_id() will return zero.

Example: A simple way to spawn an asynchronous child process.

        G::Error error;
        SpawnAsync child(command_line, &error);
        if (error.get())
        {
            // handle error
        }
        else
        {
            if (!child.execute(&error))
            {
                    // handle error
            }
        }

## Constructor & Destructor Documentation

Inti::G::SpawnAsync::SpawnAsync | ( | const std::vector< std::string > & | argv,
|  | SpawnFlagsField | flags = 0
| ) |

Constructs an asynchronous spawn object with the specified arguments argv and spawn flags.

Parameters:

  argv | A reference to a vector of std::string that holds the child's argument strings.
  flags | One or more bitflags from the G::SpawnFlags enumeration.

The first string in argv (argv[0]) is of course the name of the program to execute. By default, the name of the program must be a full path; the PATH shell variable will only be searched if you pass the G::SPAWN_SEARCH_PATH flag.

Inti::G::SpawnAsync::SpawnAsync | ( | const std::string & | command_line,
|  | G::Error * | error
| ) |

Constructs an asynchronous spawn object with the specified arguments in the command_line string.

Parameters:

  command_line | The command line string.
  error | The return location for a G::Error.

This constructor parses command line with g_shell_parse_argv() and passes it to GLib. If an error occurs it is set by the parsing function, and can be any of those from the G_SHELL_ERROR domain. Runs a command_line in the background. Unlike then other constructor, the G::SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note that G::SPAWN_SEARCH_PATH can have security implications, so consider using the other constructor if appropriate.

## Member Function Documentation

bool Inti::G::SpawnAsync::execute | ( | G::Error * | error,
|  | const ChildSetupSlot * | slot = 0
| ) |

Executes a child program asynchronously (that is, your program will not block waiting for the child to exit).

Parameters:

  error | The return location for a G::Error.
  slot | A ChildSetupSlot method to run in the child just before exec().

Returns:
  true if successful, false if error is set.

void Inti::G::SpawnAsync::set_standard_error | ( | int & | standard_error | ) |

Sets the return location for a file descriptor to read child's stderr.

Parameters:

  standard_error | The return location for the file descriptor.

void Inti::G::SpawnAsync::set_standard_input | ( | int & | standard_input | ) |

Sets the return location for a file descriptor to write to child's stdin.

Parameters:

  standard_input | The return location for the file descriptor.

void Inti::G::SpawnAsync::set_standard_output | ( | int & | standard_output | ) |

Sets the return location for a file descriptor to read child's stdout.

Parameters:

  standard_output | The return location for the file descriptor.

The documentation for this class was generated from the following file:

- spawn.h

Main Page - Footer