From 077331a23d71ba06b25290823070aeb851e2426f Mon Sep 17 00:00:00 2001
From: Peter Hutterer <peter.hutterer@who-t.net>
Date: Tue, 6 Aug 2019 08:38:47 +1000
Subject: [PATCH] doc: document that we need the O_NONBLOCK call
A large percentage of real-world use-cases are tied into some external
mainloop and require non-blocking operation. It's too easy to forget about
that, so let's add the O_NONBLOCK call to the example documentation here.
Those that don't need it can remove it easily anyway.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
---
doc/source/tutorial.rst | 18 ++++++++++++++++--
libevdev/device.py | 3 +++
2 files changed, 19 insertions(+), 2 deletions(-)
diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst
index 2f4b2a1..c8a6283 100644
--- a/doc/source/tutorial.rst
+++ b/doc/source/tutorial.rst
@@ -107,6 +107,8 @@ example above, the event type isn't needed when converting from string.
Ok, now that we know how to deal with event codes and types, we can move on
to actually using those.
+.. _opening_a_device:
+
Opening a device
----------------
@@ -118,9 +120,11 @@ devices either - you can easily figure that out yourself by looping through
the file system or using libudev.
The simplest case (and good enough for most applications) is a mere call to
-``open``::
+``open``, optionally followed by a call to ``fcntl`` to switch the file
+descriptor into non-blocking mode::
>>> fd = open("/dev/input/event0", "rb")
+ >>> fcntl.fcntl(fd, fcntl.F_SETFL, os.O_NONBLOCK)
>>> device = libevdev.Device(fd)
>>> print(device.name)
Lid Switch
@@ -130,7 +134,7 @@ events from it later or even modify the kernel device.
That's it. libevdev doesn't really care how you opened the device, as long
as ``fileno()`` works on it it'll take it. Now we can move on to actually
-handling the device
+handling the device.
Querying and modifying device capabilities
------------------------------------------
@@ -214,6 +218,16 @@ comparisons::
if btn in device.events():
print('There is a button event in there')
+The above examples all depened on whether ``os.O_NONBLOCK`` was set on the
+file descriptor after the initial ``open`` call:
+
+- ``os.O_NONBLOCK`` is set: :func:`events <libevdev.device.Device.events>`
+ returns immediately when no events are available.
+- ``os.O_NONBLOCK`` is **not** set: :func:`events
+ <libevdev.device.Device.events>` blocks until events become available
+
+See :ref:`opening_a_device` for an example on setting ``os.O_NONBLOCK``.
+
Creating uinput devices
-----------------------
diff --git a/libevdev/device.py b/libevdev/device.py
index 7f6e326..4698580 100644
--- a/libevdev/device.py
+++ b/libevdev/device.py
@@ -495,12 +495,15 @@ class Device(object):
Event processing should look like this::
fd = open("/dev/input/event0", "rb")
+ fcntl.fcntl(fd, fcntl.F_SETFL, os.O_NONBLOCK) # optional
ctx = libevdev.Device(fd)
while True:
for e in ctx.events():
print(e):
+ ... other mainloop code ...
+
This function detects if the file descriptor is in blocking or
non-blocking mode and adjusts its behavior accordingly. If the file
descriptor is in nonblocking mode and no events are available, this
--
GitLab