[[!template id=project

title="Add kqueue support to GIO"

contact="""
[tech-pkg](mailto:tech-pkg@NetBSD.org), [tech-kern](mailto:tech-kern@NetBSD.org)
"""

mentors="""
[Julio Merino](mailto:jmmv@NetBSD.org)
"""

category="pkgsrc"
difficulty="medium"
duration="3 months"

description="""
Monitoring of file system activity is a key piece of a modern desktop environment because it provides instant feedback to the user about any changes performed to the disk. In particular, file monitoring is an internal component of the Gnome infrastructure that allows the desktop to receive notifications when files or directories change. This way, if, say, you are viewing the Downloads folder in Nautilus and you start downloading a file from Epiphany into that folder, Nautilus will realize the new file and show it immediately without requiring a manual refresh.

How to monitor the file system depends on the operating system. There are basically two approaches: polling and asynchronous notifications. Polling is suboptimal because the notifications are usually delayed. Asynchronous notifications are tied to the operating system: Linux provides [inotify](http://en.wikipedia.org/wiki/Inotify), NetBSD provides [kqueue](http://en.wikipedia.org/wiki/Kqueue) and other systems provide their own APIs.

In the past, Gnome monitored the file system via a combination of [FAM](http://oss.sgi.com/projects/fam/) (a system-level service that provides an API to file system monitoring) and GNOME VFS (a high-level layer that hides the interaction with FAM). This approach was good in spirit (client/server separation) but didn't work well in NetBSD:

* FAM is abandoned.
* Does not support kqueue out of the box.
* FAM runs as root.
* FAM is too hard to set up: it requires rpcbind, an addition to etc/services, a sysctl tweak, and the configuration of a system-level daemon.

To solve some of these problems, a drop-in replacement for FAM was started. [Gamin](http://people.gnome.org/~veillard/gamin/), as it is known, still does not fix everything:

* Gamin is abandoned.
* Supports kqueue out of the box, but does not work very well.
* Actually, Gamin itself does not work. Running the tests provided by the distfile in a modern Linux system results in several test failures.

Did you notice the abandoned pattern above? This is important: in the new world order, Gnome does not use FAM any more.

The new structure to monitor files is: the low-level glib library provides the [gio](http://library.gnome.org/devel/gio/2.26/) module, which has a new file system monitoring API. The GVFS module provides higher level abstractions to file system management, and relies on gio for file system monitoring. There is no GNOME VFS any more.

The problematic point is: gio uses inotify directly; no abstraction layers in between. FAM support is still there for platforms without inotify, but as it is not used in Linux any more, both the FAM package and the support for it rot.

The goal of this project is to fix this situation. There are two possible approaches. The first is to extend the gio library with a new module to support kqueue, the native interface in NetBSD for file monitoring; this new module can be submitted upstream and will benefit all other BSD systems, but it will not help other applications that use inotify. The second is to write a compatibility library that exposes an inotify interface on top of kqueue; this cannot be sent upstream but it helps any application using inotify.

The preferred method is to write a new gio plugin to support kqueue. Henceforth, the deliverables for the project include a new gio module to support kqueue and, if time permits, a standalone library that implements an inotify interface on top of kqueue.

Assuming you are not familiar with kqueue, you might want to follow these steps to get started:

1. Read the kqueue(2) manual page to get a general idea of the API and this [example for starters](http://blog.julipedia.org/2004/10/example-of-kqueue.html).
2. Analyze the kqueue support for FAM which is in [pkgsrc/sysutils/fam/files/IMonKQueue.c++](http://cvsweb.netbsd.org/bsdweb.cgi/pkgsrc/sysutils/fam/files/IMonKQueue.c++?rev=HEAD&content-type=text/x-cvsweb-markup). This might be helpful to see how to apply kqueue to monitor for the events used by GNOME.
3. Read the modules/inotify* files in gnome-vfs and inspect how they are used in the "file method". The modules/Makefile.am contains a list of related sources in the libfile_la_SOURCES variable.
4. Possibly the hardest part: write the required stuff (modules/kqueue*) to add kqueue support.

"""

done_by="Dmitry Matveev"
]]

[[!tag gsoc]]