Xio - a 10 I/O.

Xio is lightweight, compile time customizable, constructed using a standart interfaces - traits, OS level event notification system which also includes additional components like timers, event notifications, filesystem monitoring.

This crate is under active development. The automated commit testing infrastructure will be launched soon.

Disclaimer

This code is not anyhow exists to compete or replace the Mio crate or any other crates. It appeared from the closed source code which was translated or copied to public where appropriate. Xio crate DOES NOT use/copy a code from Mio crate or any other. An API may remind a Mio's approach, but it was made this way for two reasons: another way was not found and it makes easier to replace the Mio in out projects.

Repo

A crate repo is hosed on Codeberg. Join now!

Q&A and Policies

Policy

• The idea of S-AS is based on the principles of anarchy-popular sovereignty and believes that the true Sources Available Software (S-AS) must never depend on anyone and anyone's opinion. It is entirely on its own and does not guarantee/promise you anything.
• This crate i.e code is NOT an Open Source software. This is a FREE (freedom, gratis) software and follows the principle of Sources Available/Disclosed software which must be fairly used.
• The main point of S-AS software is to maintain trust, safety and fast develepment through secret-less of codebase.
• It is published under FSF/OSI approved licenses however author does not follow/share/respect OSI and FSF principles and phylosophy.
• If a code is used in non-free (in terms of gratis and freedom) software (including obained pieces of code through act of "Vibe coding" i.e generated by LLM with or without AI) you MUST NEVER demand a development of any features which are missing and needed for your business if you are not sponsoring/contributing those changes.
• Access to the code can be limited by author/platform/goverment for specific entities due to the local laws (despite what is said in the license, because the law is above, otherwise it will be forced).
• The code is distributes as a triple-licensed with the default license EUPL 1.2 if not stated otherwise. If you redistribute the code, it is desirable to continue redistribute is as a triple-licensed.

Version

0.1.0-alpha.3 Rust version 2024 min 1.85.

Changelog

License:

Sources are available under licenses: EUPL-1.2 OR MPL-2.0 OR MIT

Default is EUPL-1.2. The license which was selected should be specified anywhere i.e in comments in the larger project, otherwise it is EUPL-1.2.

Supports:

• Windows:
• • Register both handle and sockets.
• • Event notification system: IOCP XioEsIocp:
• • • AFP - Auxiliary Function Pack for the sockets polling.
• • • SCP - Source Completion Pack for the handle polling.
• • • EVE - EventPort for events or anything which uses IOCP port.
• • • RIO - Registered IO (in-progress)
• • Event notification system: XioEsWfmo WFMO (WaitForMultipleObjects) has a limitation to 64 objects.
• • Timer XioTimerEvent based on CreateWaitableTimerExW.
• • Event notifications:
• • • A XioEventA based on CreateEventA.
• • • A XioEventP based on IOCP EVE driver.
• • FS Notification XioWinFs based on FindFirstChangeNotificationA limited to directories only.
• • MPSC with notification event based on the crossbeam.
• Unix:
• • Network socket split.
• • Event notification system: XioEsEpoll based on EPOLL
• • Event notification system: XioEsPoll based on POLL
• • Event notification system: XioEsKqueue based on KQUEUE
• • Timers:
• • • A XioTimerFd based on the timerfd
• • • A XioKTimerFd based on the kqueuefd
• • • A XioKTimerUser based on the kqueue port.
• • Event notifications:
• • • XioEventFd based on the eventfd
• • • XioEventKqFd based on the kqueue fd.
• • • XioEventKqUser based on the kqueue port.
• • FS Notifications:
• • • XioInotifyFd based on the inotify
• • • XioKqueueFs based on the kqueue
• • MPSC with notification event based on the crossbeam.

ToDo:

• Windows:
• • RIO driver completion
• • io_uring
• • Pipes
• • testing
• Unix
• • Linux:
• • • uring async IO
• • • testing
• • FreeBSD and other BSD systems excluding OSX
• • • KQueue AIO/LIO
• • • Testing
• • OSX
• • Grand Central Dispatch ?? implementations
• Redox:
• • Add support for Redox
• WASM:
• • Is it needed?
• Misc:
• • Event tracing
• • More tests
• • More examples
• • standartization documents and documentation

OS support

• A Tier 1 is UNIX and REDOX as a Free Software.
• A TIer 10 is Windows and OSX as non-free or partialy free.

Automatic testing

This crate is on a early stages and is verified manually on different OSes. A automatic testing of the code will be added as soon as crate would reach a stable 0.1.0 version. The main problem with it is that Windows instances are expensive and OSX cannot be installed on non-approved hardware. However, I bought a Mac Mini M2 and a small Windows 11 box which will be used for this purposes. For the FreeBSD/Linux/Redox a VPS will be rented.

Examples

At first you need to select the type of ENS - event notification system. A list is available on the lib.rs.

For example, a Linux is a target OS.

Initializing a registry

// creating a registry
let mut reg = XioPollRegistry::<XioEsEpoll>::new().unwrap();

Then you need to preallocate the memory for the events storage:

let mut event_buf = XioPollRegistry::<XioEsEpoll>::allocate_events(128.try_into().unwrap());   

Now, the FDs or features can be added. Lets create a timer and register it with UID 2.

const TIMEOUT: XioEventUid = XioEventUid::manual(2);

// initializaing a timer
let mut timeout_0 = 
    XioTimer::<XioTimerFd>::new(XioTimerType::CLOCK_REALTIME, XioTimerFlags::TFD_NONBLOCK).unwrap();
    
// registering a timer
reg
    .get_registry()
    .en_register(&mut timeout_0, TIMEOUT, XioChannel::INPUT)
    .unwrap();

Now, lets create a UDP socket and also register it with the UID:1

const LISTENER: XioEventUid = XioEventUid::manual(1);

let addr = "127.0.0.1:0";
let server = UdpSocket::bind(addr).unwrap();

// registering the socket in the registry
// XioEventSource<UdpSocket, XioEsEpoll>
let wr_server = 
    reg
        .get_registry()
        .en_register_wrap(server, LISTENER, XioChannel::INPUT)
        .unwrap();

As you can see, a timer was registered as an instance, but FD was returned as a wrapped value. All items which implements AsFd and AsRawFd are wrapped into XioEventSource. A socket can be wrapped separatly into XioEventSource. It is needed for many reasons: auto managment, FD Input/Output splitting.

Lets setup timer in oneshot mode, relative time 15 seconds.

// setting timer in oneshot mode
let timeout = 
    XioTimerExpireMode::<XioRelativeTime>::new_oneshot( XioRelativeTime::from(Duration::from_secs(15)));

// start timer
timeout_0.get_timer().set_time(timeout).unwrap();

And now output the message and poll:

println!("listening: {}, connect using 'nc -u 127.0.0.1 {}'", addr, wr_server.inner().local_addr().unwrap().port());

let mut buf = [0_u8; 0xFFFF];

loop
{
    // polling for the event
    let res = 
        reg.poll(&mut event_buf, XioTimeout::Blocking);

    if let Err(ref e) = res && e.kind() == ErrorKind::Interrupted
    {
        println!("interrupted poll");
        continue;
    }

    res.unwrap();

    
    for ev in event_buf.ev_get_iter()
    {
        match ev.get_uid()
        {
            LISTENER => 
            {
                // disarm timer
                timeout_0.get_timer().unset_time().unwrap();

                loop
                {
                    let rcv_res = 
                        wr_server.inner().recv_from(&mut buf);

                    if let Ok((n, from)) = rcv_res
                    {
                        println!("received pkt from {}, size: {}", from, n);

                        println!("data: {}", String::from_utf8_lossy(&buf[..n]));

                        wr_server.inner().send_to(b"message received!", from).unwrap();
                    }
                    else if let Err(e) = rcv_res.as_ref() && e.kind() == ErrorKind::WouldBlock
                    {
                        // return to the poll, because no more to read has left.
                        break;
                    }
                    else
                    {
                        rcv_res.unwrap();   
                    }
                }

                // start timer again
                timeout_0.get_timer().set_time(timeout).unwrap();
            },
            TIMEOUT => 
            {
                println!("ops, timeout no events.");
                return;
            },
            uid => 
                println!("unknwon event with uid: {}", uid)
        }
    }
}

The code above outputs the received message as soon as LISTENER fires an event. A timer is reset each time the message arrives. A TIMEOUT UID is an event handler for timer. It it fires an event, a program ends.