abstract class Crystal::EventLoop::Polling

• Crystal::EventLoop::Polling
• Crystal::EventLoop
• Reference
• Object

Overview

Polling EventLoop.

This is the abstract interface that implements Crystal::EventLoop for polling based UNIX targets, such as epoll (linux), kqueue (bsd), or poll (posix) syscalls. This class only implements the generic parts for the external world to interact with the loop. A specific implementation is required to handle the actual syscalls. See Crystal::Epoll::EventLoop and Crystal::Kqueue::EventLoop.

The event loop registers the fd into the kernel data structures when an IO operation would block, then keeps it there until the fd is closed.

NOTE the fds must have O_NONBLOCK set.

It is possible to have multiple event loop instances, but an fd can only be in one instance at a time. When trying to block from another loop, the fd will be removed from its associated loop and added to the current one (this is automatic). Trying to move a fd to another loop with pending waiters is unsupported and will raise an exception. See PollDescriptor#remove.

A timed event such as sleep or select timeout follows the following logic:

1. create an Event (actually reuses it, see FiberChannel);
2. register the event in @timers;
3. supend the current fiber.

The timer will eventually trigger and resume the fiber. When an IO operation on fd would block, the loop follows the following logic:

1. register the fd (once);
2. create an Event;
3. suspend the current fiber;

When the IO operation is ready, the fiber will eventually be resumed (one fiber at a time). If it's an IO operation, the operation is tried again which may block again, until the operation succeeds or an error occured (e.g. closed, broken pipe).

If the IO operation has a timeout, the event is also registered into @timers before suspending the fiber, then after resume it will raise IO::TimeoutError if the event timed out, and continue otherwise.

Direct Known Subclasses

• Crystal::EventLoop::Epoll

Defined in:

Instance Method Summary

• #accept(socket : ::Socket) : ::Socket::Handle | Nil

  Accepts an incoming TCP connection on the socket.

• #after_fork : Nil

  no parallelism issues, but let's clean-up anyway

• #after_fork_before_exec : Nil

  reset the mutexes since another thread may have acquired the lock of one event loop, which would prevent closing file descriptors for example.

• #close(file_descriptor : System::FileDescriptor) : Nil

  Closes the file descriptor resource.

• #close(socket : ::Socket) : Nil

  Closes the socket.

• #connect(socket : ::Socket, address : ::Socket::Addrinfo | ::Socket::Address, timeout : Time::Span | Nil) : IO::Error | Nil

  Opens a connection on socket to the target address.

• #create_resume_event(fiber : Fiber) : FiberEvent

  Create a new resume event for a fiber.

• #create_timeout_event(fiber : Fiber) : FiberEvent

  Creates a timeout_event.

• #read(file_descriptor : System::FileDescriptor, slice : Bytes) : Int32

  Reads at least one byte from the file descriptor into slice.

• #read(socket : ::Socket, slice : Bytes) : Int32

  Reads at least one byte from the socket into slice.

• #receive_from(socket : ::Socket, slice : Bytes) : Tuple(Int32, ::Socket::Address)

  Receives at least one byte from the socket into slice, capturing the source address.

• #run(blocking : Bool) : Bool

  NOTE thread unsafe

• #send_to(socket : ::Socket, slice : Bytes, address : ::Socket::Address) : Int32

  Sends at least one byte from slice to the socket with a target address address.

• #write(file_descriptor : System::FileDescriptor, slice : Bytes) : Int32

  Writes at least one byte from slice to the file descriptor.

• #write(socket : ::Socket, slice : Bytes) : Int32

  Writes at least one byte from slice to the socket.

Instance Method Detail