class IO - io/nonblock: Ruby Standard Library Documentation

# class IO

### Public Instance Methods

nonblock {|io| } → object click to toggle source
nonblock(boolean) {|io| } → object

Yields `self` in non-blocking mode.

When `false` is given as an argument, `self` is yielded in blocking mode. The original mode is restored after the block is executed.

    static VALUE
    rb_io_nonblock_block(int argc, VALUE *argv, VALUE self)
    {
        int nb = 1;

        int descriptor = rb_io_descriptor(self);

        if (argc > 0) {
            VALUE v;
            rb_scan_args(argc, argv, "01", &v);
            nb = RTEST(v);
        }

        int current_flags = get_fcntl_flags(descriptor);
        int restore[2] = {descriptor, current_flags};

        if (!io_nonblock_set(descriptor, current_flags, nb))
            return rb_yield(self);

        return rb_ensure(rb_yield, self, io_nonblock_restore, (VALUE)restore);
    }

nonblock = boolean → boolean click to toggle source

Enables non-blocking mode on a stream when set to `true`, and blocking mode when set to `false`.

This method set or clear O_NONBLOCK flag for the file descriptor in ios.

The behavior of most `IO` methods is not affected by this flag because they retry system calls to complete their task after EAGAIN and partial read/write. (An exception is IO#syswrite which doesn’t retry.)

This method can be used to clear non-blocking mode of standard I/O. Since nonblocking methods (read_nonblock, etc.) set non-blocking mode but they doesn’t clear it, this method is usable as follows.

    END { STDOUT.nonblock = false }
    STDOUT.write_nonblock("foo")

Since the flag is shared across processes and many non-Ruby commands doesn’t expect standard I/O with non-blocking mode, it would be safe to clear the flag before Ruby program exits.

For example following Ruby program leaves STDIN/STDOUT/STDER non-blocking mode. (STDIN, STDOUT and STDERR are connected to a terminal. So making one of them nonblocking-mode effects other two.) Thus cat command try to read from standard input and it causes “Resource temporarily unavailable” error (EAGAIN).

    % ruby -e '
    STDOUT.write_nonblock("foo\n")'; cat
    foo
    cat: -: Resource temporarily unavailable

Clearing the flag makes the behavior of cat command normal. (cat command waits input from standard input.)

    % ruby -rio/nonblock -e '
    END { STDOUT.nonblock = false }
    STDOUT.write_nonblock("foo")
    '; cat
    foo

    static VALUE
    rb_io_nonblock_set(VALUE self, VALUE value)
    {
        if (RTEST(value)) {
            rb_io_t *fptr;
            GetOpenFile(self, fptr);
            rb_io_set_nonblock(fptr);
        }
        else {
            int descriptor = rb_io_descriptor(self);
            io_nonblock_set(descriptor, get_fcntl_flags(descriptor), RTEST(value));
        }

        return self;
    }

nonblock? → boolean click to toggle source

Returns `true` if an `IO` object is in non-blocking mode.

    static VALUE
    rb_io_nonblock_p(VALUE io)
    {
        if (get_fcntl_flags(rb_io_descriptor(io)) & O_NONBLOCK)
            return Qtrue;
        return Qfalse;
    }