TIP #10000 Version 1.200: Dummy Proposal for Testing Editing Interfaces

This is not necessarily the current version of this TIP.

Abstract

This proposal has no content. It exists only to provide a document on which testing of and practice using of the TIP editing interfaces can take place.

This TIP proposes to add capabilities for monitoring changes in the file system to the Tcl core.

Examples

   # pad out 12 nuls, then set cursor to 0, write an 
   #   int, record position, then write another int.
   set data [binary format "x# @0 I p I" 12 1 pos 42]
   --> data: "\0\0\0\1\0\0\0\x2A\0\0\0\0"  pos: 4

   # set cursor position from value of first param, scan 
   # three items from the data and write them to the
   # next three parameter variables, then write new cursor
   # position to next parameter variable.
   binary scan $data "@# Iss p" $pos beI leS1 leS2 pos
   --> beI: 42  leS1:0 leS2:0 pos:12

# 4 is value for "#", no further param, thus return # result for "I" set val [binary scan $data "@# I" 4] --> val: 42

# extra "further ideas" feature

set val [binary scan $data "@# I p" 4 pos] --> val: 42 pos: 8

Rationale

Most if not all platforms supported by Tcl today allow user space processes to monitor the file system for certain changes such as the creation, deletion, alteration or renaming of files.

Unfortunately there is no unique cross-platform API for this, so a Tcl core feature will have to be backed by a series of platform-dependent implementations and possibly a fallback for platforms that don't have these monitoring capabilities or instances on which they have been disabled.

Platform-speciffic APIs which should be supported by the final implementation (list to be extended):

• inotify[1] (Linux)

• kqueue[2] (BSD)

• FSEvents[3] (Mac OS X)

• (Windows?)

Proposal

A new subcommand should get added to the file command with the following syntax:

file monitor path callback ?filter?

This will register callback to be called from the event loop when one of the events specified by filter occurs to the file or directory specified by path. Calling file monitor with an empty callback argument removes an existing callback from the given path.

The calling conventions for callback and the syntax of filter are yet to be determined.

Rejected alternatives

The file command was chosen over fileevent and chan event, because the object to be monitored is passed by name and not as an open channel.

As an API, FAM[4] would have been a more portable alternative, but it requres a daemon to be running on the local machine and it requires linking against a lib that is licensed under the LGPL. It might be possible to support FAM as a compile time alternative to the system's native notification method. There exists a serverless implementation of a subset of the FAM API, called Gamin[5], but that's also licensed under the LGPL.

There exists a Tcl extension for inotify[6], but it is licensed under the GPL and it's script level API is too close to the inotify primitives to serve as the basis of a cross-platform abstraction for such notifications. But it might be a good base for a scripted prototype to sort out the remaining details of the proposed script level API.

Further ideas

It might be an option to release the C code that unifies the various OS speciffic mechanisms under a single API as a separate library, so that projects other than Tcl can use it as well.

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.