Author:         Andreas Leitgeb <avl@logic.at>
State:          Draft
Type:           Project
Vote:           Pending
Created:        16-Apr-2017
Post-History:   
Keywords:       Tcl,event handling
Tcl-Version:    8.7
Tcl-Branch:     tip-469

Abstract

This TIP proposes to extend the fileevent Tcl command to also accept the keyword exception for its second argument. This will allow to register a callback for the specific event that the OS reports an exception on the channel, while ignoring read- or writability.

Rationale

Tcl already allows registering for exceptions in its C-API function Tcl_CreateChannelHandler(). This TIP merely enables the command fileevent to pass TCL_EXCEPTION for the mask in the call to Tcl_CreateChannelHandler().

On Linux, there exist special "files" that are always readable or writable without blocking, but certain (hardware-related) events are reported as exceptions on the channel. The example at hand is the "sysfs"-API for GPIO (general purpose input output) where level-changes on GPIO pins are reported as exceptions on the channel. For details see https://www.kernel.org/doc/Documentation/gpio/sysfs.txt and the paragraphs about "value".

Listening for readable plus exceptions (as Tcl automatically does when asking for readable event) doesn't help here, because then the event would continuously fire, as reading the current level on a pin never blocks.

The only way to react to level-changes (short of busy-looping) is to have the internal select/poll call specify exclusively the exception notification for that channel.

Specification

This document proposes to add the keyword exception to the fileevent command, where so far only readable and writable are allowed.

If exception is given as event specifier, then a handler script is registered, cleared or queried just like with readable or writable.

Since readable or writable already check for exception as well, registering an exception event for a channel that already has readable and/or writable handlers registered makes little sense, but allowing it does not raise any issues that having both readable and writable handlers wouldn't already have, so being fussy about it would confuse more than it could help to avoid confusion.

Alternatives

The piio extension provides event registration on its own, but its support for certain IO-chipsets lags behind the sysfs-API.

With exception becoming its own event type, then readable and writable would no longer need to also fire on exceptions, but compatibility forbids this particular follow-up change.

Compatibility

No incompatibilities are introduced.

Reference Implementation

A really bare-bones reference implementation is available as a patch http://paste.tclers.tk/4231 . Also, a branch named tip-469 in fossil has been created: https://core.tcl-lang.org/tcl/timeline?r=tip-469 .

A thus-patched tclsh can successfully wait for input-level changes on TIP-author's "nano-pi" raspberryPI-like platform with a chipset not yet supported by piio.

Documentation and test updates yet to be done.

Copyright

This document has been placed in the public domain.