Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# `gevent.os` – Low-level operating system functions from `os`

Low-level operating system functions from `os`.

## Cooperative I/O

This module provides cooperative versions of `os.read()` and `os.write()`. These functions are not monkey-patched; you must explicitly call them or monkey patch them yourself.

### POSIX functions

On POSIX, non-blocking IO is available.

- `nb_read()`

- `nb_write()`

- `make_nonblocking()`

### All Platforms

On non-POSIX platforms (e.g., Windows), non-blocking IO is not available. On those platforms (and on POSIX), cooperative IO can be done with the threadpool.

- `tp_read()`

- `tp_write()`

## Child Processes

The functions `fork()` and (on POSIX) `forkpty()` and `waitpid()` can be used to manage child processes.

Warning

Forking a process that uses greenlets does not eliminate all non-running greenlets. Any that were scheduled in the hub of the forking thread in the parent remain scheduled in the child; compare this to how normal threads operate. (This behaviour may change is a subsequent major release.)

fork(*args, **kwargs)

  Forks a child process and starts a child watcher for it in the parent process so that `waitpid` and SIGCHLD work as expected.

  This implementation of `fork` is a wrapper for `fork_and_watch()` when the environment variable `GEVENT_NOWAITPID` is not defined. This is the default and should be used by most applications.

  Changed in version 1.1b2.

fork_and_watch(callback=None, loop=None, ref=False, fork=<function fork_gevent>)

  Fork a child process and start a child watcher for it in the parent process.

  This call cooperates with `waitpid()` to enable cooperatively waiting for children to finish. When monkey-patching, these functions are patched in as `os.fork()` and `os.waitpid()`, respectively.

  In the child process, this function calls `gevent.hub.reinit()` before returning.

  Availability: POSIX.

  Parameters:

    - callback – If given, a callable that will be called with the child watcher when the child finishes.

    - loop – The loop to start the watcher in. Defaults to the loop of the current hub.

    - fork – The fork function. Defaults to `the one defined in this module` (which automatically calls `gevent.hub.reinit()`). Pass the builtin `os.fork()` function if you do not need to initialize gevent in the child process.

  Added in version 1.1b1.

  See also

  `gevent.monkey.get_original()` To access the builtin `os.fork()`.

fork_gevent()

  Forks the process using `os.fork()` and prepares the child process to continue using gevent before returning.

  Note

  The PID returned by this function may not be waitable with either the original `os.waitpid()` or this module’s `waitpid()` and it may not generate SIGCHLD signals if libev child watchers are or ever have been in use. For example, the `gevent.subprocess` module uses libev child watchers (which parts of gevent use libev child watchers is subject to change at any time). Most applications should use `fork_and_watch()`, which is monkey-patched as the default replacement for `os.fork()` and implements the `fork` function of this module by default, unless the environment variable `GEVENT_NOWAITPID` is defined before this module is imported.

  Added in version 1.1b2.

forkpty(*args, **kwargs)

  Like `fork()`, but using `forkpty_gevent()`.

  This implementation of `forkpty` is a wrapper for `forkpty_and_watch()` when the environment variable `GEVENT_NOWAITPID` is not defined. This is the default and should be used by most applications.

  Added in version 1.1b5.

forkpty_and_watch(callback=None, loop=None, ref=False, forkpty=<function forkpty_gevent>)

  Like `fork_and_watch()`, except using `forkpty_gevent()`.

  Availability: Some Unix systems.

  Added in version 1.1b5.

forkpty_gevent()

  Forks the process using `os.forkpty()` and prepares the child process to continue using gevent before returning.

  Returns a tuple (pid, master_fd). The `master_fd` is not put into non-blocking mode.

  Availability: Some Unix systems.

  See also

  This function has the same limitations as `fork_gevent()`.

  Added in version 1.1b5.

make_nonblocking(fd)

  Put the file descriptor fd into non-blocking mode if possible.

  Returns:

    A boolean value that evaluates to True if successful.

nb_read(fd, n)

  Read up to n bytes from file descriptor fd. Return a byte string containing the bytes read, which may be shorter than n. If end-of-file is reached, an empty string is returned.

  The descriptor must be in non-blocking mode.

nb_write(fd, buf)

  Write some number of bytes from buffer buf to file descriptor fd. Return the number of bytes written, which may be less than the length of buf.

  The file descriptor must be in non-blocking mode.

tp_read(fd, n)

  Read up to n bytes from file descriptor fd. Return a string containing the bytes read. If end-of-file is reached, an empty string is returned.

  Reading is done using the threadpool.

tp_write(fd, buf)

  Write bytes from buffer buf to file descriptor fd. Return the number of bytes written.

  Writing is done using the threadpool.

waitpid(pid, options)

  Wait for a child process to finish.

  If the child process was spawned using `fork_and_watch()`, then this function behaves cooperatively. If not, it may have race conditions; see `fork_gevent()` for more information.

  The arguments are as for the underlying `os.waitpid()`. Some combinations of options may not be supported cooperatively (as of 1.1 that includes WUNTRACED). Using a pid of 0 to request waiting on only processes from the current process group is not cooperative. A pid of -1 to wait for any child is non-blocking, but may or may not require a trip around the event loop, depending on whether any children have already terminated but not been waited on.

  Availability: POSIX.

  Added in version 1.1b1.

  Changed in version 1.2a1: More cases are handled in a cooperative manner.