class IO - io/wait: Ruby Standard Library Documentation

# class IO

### Public Instance Methods

nread → int click to toggle source

Returns number of bytes that can be read without blocking. Returns zero if no information available.

You must require ‘io/wait’ to use this method.

    static VALUE
    io_nread(VALUE io)
    {
        rb_io_t *fptr;
        int len;
        ioctl_arg n;

        GetOpenFile(io, fptr);
        rb_io_check_readable(fptr);
        len = rb_io_read_pending(fptr);
        if (len > 0) return INT2FIX(len);

    #ifdef HAVE_RB_IO_DESCRIPTOR
        int fd = rb_io_descriptor(io);
    #else
        int fd = fptr->fd;
    #endif

        if (!FIONREAD_POSSIBLE_P(fd)) return INT2FIX(0);
        if (ioctl(fd, FIONREAD, &n)) return INT2FIX(0);
        if (n > 0) return ioctl_arg2num(n);
        return INT2FIX(0);
    }

ready? → truthy or falsy click to toggle source

Returns a truthy value if input available without blocking, or a falsy value.

You must require ‘io/wait’ to use this method.

    static VALUE
    io_ready_p(VALUE io)
    {
        rb_io_t *fptr;
    #ifndef HAVE_RB_IO_WAIT
        struct timeval tv = {0, 0};
    #endif

        GetOpenFile(io, fptr);
        rb_io_check_readable(fptr);
        if (rb_io_read_pending(fptr)) return Qtrue;

    #ifndef HAVE_RB_IO_WAIT
        return wait_for_single_fd(fptr, RB_WAITFD_IN, &tv) ? Qtrue : Qfalse;
    #else
        return io_wait_event(io, RUBY_IO_READABLE, RB_INT2NUM(0), 1);
    #endif
    }

wait(events, timeout) → event mask, false or nil click to toggle source
wait(timeout = nil, mode = :read) → self, true, or false

Waits until the `IO` becomes ready for the specified events and returns the subset of events that become ready, or a falsy value when times out.

The events can be a bit mask of `IO::READABLE`, `IO::WRITABLE` or `IO::PRIORITY`.

Returns a truthy value immediately when buffered data is available.

Optional parameter `mode` is one of `:read`, `:write`, or `:read_write`.

You must require ‘io/wait’ to use this method.

    static VALUE
    io_wait(int argc, VALUE *argv, VALUE io)
    {
    #ifndef HAVE_RB_IO_WAIT
        rb_io_t *fptr;
        struct timeval timerec;
        struct timeval *tv = NULL;
        int event = 0;
        int i;

        GetOpenFile(io, fptr);
        for (i = 0; i < argc; ++i) {
            if (SYMBOL_P(argv[i])) {
                event |= wait_mode_sym(argv[i]);
            }
            else {
                *(tv = &timerec) = rb_time_interval(argv[i]);
            }
        }
        /* rb_time_interval() and might_mode() might convert the argument */
        rb_io_check_closed(fptr);
        if (!event) event = RB_WAITFD_IN;
        if ((event & RB_WAITFD_IN) && rb_io_read_pending(fptr))
            return Qtrue;
        if (wait_for_single_fd(fptr, event, tv))
            return io;
        return Qnil;
    #else
        VALUE timeout = Qundef;
        rb_io_event_t events = 0;
        int i, return_io = 0;

        /* The documented signature for this method is actually incorrect.
         * A single timeout is allowed in any position, and multiple symbols can be given.
         * Whether this is intentional or not, I don't know, and as such I consider this to
         * be a legacy/slow path. */
        if (argc != 2 || (RB_SYMBOL_P(argv[0]) || RB_SYMBOL_P(argv[1]))) {
            /* We'd prefer to return the actual mask, but this form would return the io itself: */
            return_io = 1;

            /* Slow/messy path: */
            for (i = 0; i < argc; i += 1) {
                if (RB_SYMBOL_P(argv[i])) {
                    events |= wait_mode_sym(argv[i]);
                }
                else if (timeout == Qundef) {
                    rb_time_interval(timeout = argv[i]);
                }
                else {
                    rb_raise(rb_eArgError, "timeout given more than once");
                }
            }

            if (timeout == Qundef) timeout = Qnil;

            if (events == 0) {
                events = RUBY_IO_READABLE;
            }
        }
        else /* argc == 2 and neither are symbols */ {
            /* This is the fast path: */
            events = io_event_from_value(argv[0]);
            timeout = argv[1];
        }

        if (events & RUBY_IO_READABLE) {
            rb_io_t *fptr = NULL;
            RB_IO_POINTER(io, fptr);

            if (rb_io_read_pending(fptr)) {
                /* This was the original behaviour: */
                if (return_io) return Qtrue;
                /* New behaviour always returns an event mask: */
                else return RB_INT2NUM(RUBY_IO_READABLE);
            }
        }

        return io_wait_event(io, events, timeout, return_io);
    #endif
    }

wait_priority → truthy or falsy click to toggle source
wait_priority(timeout) → truthy or falsy

Waits until `IO` is priority and returns a truthy value or a falsy value when times out. Priority data is sent and received using the Socket::MSG_OOB flag and is typically limited to streams.

You must require ‘io/wait’ to use this method.

    static VALUE
    io_wait_priority(int argc, VALUE *argv, VALUE io)
    {
        rb_io_t *fptr = NULL;

        RB_IO_POINTER(io, fptr);
        rb_io_check_readable(fptr);

        if (rb_io_read_pending(fptr)) return Qtrue;

        rb_check_arity(argc, 0, 1);
        VALUE timeout = argc == 1 ? argv[0] : Qnil;

        return io_wait_event(io, RUBY_IO_PRIORITY, timeout, 1);
    }

wait_readable → truthy or falsy click to toggle source
wait_readable(timeout) → truthy or falsy

Waits until `IO` is readable and returns a truthy value, or a falsy value when times out. Returns a truthy value immediately when buffered data is available.

You must require ‘io/wait’ to use this method.

    static VALUE
    io_wait_readable(int argc, VALUE *argv, VALUE io)
    {
        rb_io_t *fptr;
    #ifndef HAVE_RB_IO_WAIT
        struct timeval timerec;
        struct timeval *tv;
    #endif

        GetOpenFile(io, fptr);
        rb_io_check_readable(fptr);

    #ifndef HAVE_RB_IO_WAIT
        tv = get_timeout(argc, argv, &timerec);
    #endif
        if (rb_io_read_pending(fptr)) return Qtrue;

    #ifndef HAVE_RB_IO_WAIT
        if (wait_for_single_fd(fptr, RB_WAITFD_IN, tv)) {
            return io;
        }
        return Qnil;
    #else
        rb_check_arity(argc, 0, 1);
        VALUE timeout = (argc == 1 ? argv[0] : Qnil);

        return io_wait_event(io, RUBY_IO_READABLE, timeout, 1);
    #endif
    }

wait_writable → truthy or falsy click to toggle source
wait_writable(timeout) → truthy or falsy

Waits until `IO` is writable and returns a truthy value or a falsy value when times out.

You must require ‘io/wait’ to use this method.

    static VALUE
    io_wait_writable(int argc, VALUE *argv, VALUE io)
    {
        rb_io_t *fptr;
    #ifndef HAVE_RB_IO_WAIT
        struct timeval timerec;
        struct timeval *tv;
    #endif

        GetOpenFile(io, fptr);
        rb_io_check_writable(fptr);

    #ifndef HAVE_RB_IO_WAIT
        tv = get_timeout(argc, argv, &timerec);
        if (wait_for_single_fd(fptr, RB_WAITFD_OUT, tv)) {
            return io;
        }
        return Qnil;
    #else
        rb_check_arity(argc, 0, 1);
        VALUE timeout = (argc == 1 ? argv[0] : Qnil);

        return io_wait_event(io, RUBY_IO_WRITABLE, timeout, 1);
    #endif
    }