8.2 Integrating with external Lisp packages

In general, it is not recommended to use TRAMP functions and variables not described in this manual. They might change their signature and/or semantics without any announcement.

8.2.1 File name completion

Sometimes, it is not convenient to open a new connection to a remote host, including entering the password and alike. For example, this is nasty for packages providing file name completion. Such a package could signal to TRAMP, that they don’t want it to establish a new connection. Use the variable non-essential temporarily and bind it to non-nil value.

(let ((non-essential t))
  …)

8.2.2 File attributes cache

Keeping a local cache of remote file attributes in sync with the remote host is a time-consuming operation. Flushing and re-querying these attributes can tax TRAMP to a grinding halt on busy remote hosts.

To get around these types of slow-downs in TRAMP’s responsiveness, set the process-file-side-effects to nil to stop TRAMP from flushing the cache. This is helpful in situations where callers to process-file know there are no file attribute changes. The let-bind form to accomplish this:

(let (process-file-side-effects)
  …)

For asynchronous processes, TRAMP uses a process sentinel to flush file attributes cache. When callers to start-file-process know beforehand no file attribute changes are expected, then the process sentinel should be set to the default state. In cases where the caller defines its own process sentinel, TRAMP’s process sentinel is overwritten. The caller can still flush the file attributes cache in its process sentinel with this code:

(unless (memq (process-status proc) '(run open))
  (dired-uncache remote-directory))

Since TRAMP traverses subdirectories starting with the root directory, it is most likely sufficient to make the default-directory of the process buffer as the root directory.

8.2.3 Timers

Timers run asynchronously at any time when Emacs is waiting for sending a string to a process, or waiting for process output. They can run any remote file operation, which would conflict with the already running remote file operation, if the same connection is affected. TRAMP detects this situation, and raises the remote-file-error error. A timer function should avoid this situation. As a minimum, it should protect itself against this error, by wrapping the timer function body as follows:

(ignore-error 'remote-file-error
  …)