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.

New 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.

New 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.

New 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.

New 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().

New 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.

New in version 1.1b1.

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

Next page: gevent.pool – Managing greenlets in a group