Kqueue Wrapper in Rust

This challenge asks you to create a basic wrapper around the kqueue system call in Rust. kqueue is a powerful event notification mechanism available on BSD-based systems (like macOS and FreeBSD) that allows a single process to monitor multiple file descriptors and other kernel objects for various events (e.g., readability, writability, errors). Building a wrapper provides a safer and more idiomatic Rust interface to this low-level functionality.

Problem Description

You are tasked with creating a Kqueue struct in Rust that encapsulates the functionality of the kqueue system call. This struct should provide methods for:

Initialization: Creating a new kqueue instance.
Adding Events: Registering a file descriptor (represented as a std::os::fd::RawFd) with the kqueue and specifying the events to monitor (read, write, exception).
Waiting for Events: Blocking until events occur on the registered file descriptors. This method should return a vector of Event structs.
Cleanup: Closing the kqueue instance and releasing associated resources.

The Event struct should contain the file descriptor and the set of events that occurred.

Key Requirements:

Use the nix crate for interacting with the underlying system calls (specifically nix::sys::kqueue). You'll need to add nix = "0.27" to your Cargo.toml.
Handle potential errors from the kqueue system calls gracefully.
Provide a safe and idiomatic Rust interface.
The Kqueue struct should own the kqueue descriptor.
The Waiting for Events method should return a Result<Vec<Event>, nix::Error> to handle potential errors during the wait.

Expected Behavior:

Creating a Kqueue should succeed if the system supports kqueue.
Adding events should succeed if the file descriptor is valid and the events are supported.
Waiting for events should block until at least one event occurs.
Closing the Kqueue should release the underlying system resource.

Edge Cases to Consider:

Invalid file descriptors.
Unsupported events.
Errors during the kqueue system calls (e.g., insufficient resources).
Signals interrupting the wait call. (While not required to handle signals explicitly, be aware that they can occur.)
The kqueue being closed while events are still pending.

Examples

Example 1:

Input:  A Kqueue instance, a file descriptor 1, and the events Read | Write.
Output:  A vector of Event structs, potentially empty if no events occur during the wait.
Explanation:  The Kqueue instance monitors file descriptor 1 for read and write events. The wait function blocks until either event occurs, then returns a vector containing the file descriptor and the events that occurred.

Example 2:

Input: A Kqueue instance, a file descriptor 2, and the event Exception.
Output: A vector of Event structs, potentially containing an Exception event if an error occurs on file descriptor 2.
Explanation: The Kqueue instance monitors file descriptor 2 for exception events. If an error occurs on the file descriptor, the wait function will return an Event struct indicating the exception.

Example 3: (Edge Case)

Input: A Kqueue instance and an invalid file descriptor (-1).
Output: An error is returned when attempting to add the event.
Explanation: Attempting to register an invalid file descriptor with the kqueue should result in an error.

Constraints

The kqueue wrapper should be compatible with BSD-based systems (macOS, FreeBSD).
The wait function should block for a maximum of 10 seconds. (This can be implemented using a timeout in the nix::sys::kqueue::wait call).
The code should be well-documented and easy to understand.
Error handling should be robust and informative.

Notes

The nix crate provides low-level bindings to system calls. Refer to its documentation for details on the kqueue functions.
Consider using Rust's Result type to handle potential errors.
Think about how to represent the events (e.g., using a bitmask or an enum).
This is a simplified wrapper. A production-ready wrapper might include more features, such as support for timers and synchronization primitives.
Focus on correctness and safety first. Performance optimizations can be considered later.
The Event struct should be defined as: struct Event { fd: std::os::fd::RawFd, events: nix::sys::kqueue::EventSet }