hurd/translator_short-circuiting -> hurd/translator/short-circuiting

1 files changed, 59 insertions, 0 deletions

diff --git a/hurd/translator/short-circuiting.mdwn b/hurd/translator/short-circuiting.mdwn
new file mode 100644
index 00000000..01bd6ccb
--- /dev/null
+++ b/hurd/translator/short-circuiting.mdwn
@@ -0,0 +1,59 @@
+[[!meta copyright="Copyright © 2009 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled
+[[GNU Free Documentation License|/fdl]]."]]"""]]
+
+# Translator short-circuiting
+
+In traditional Unix filesystems contain special files.  These are:
+symbolic links, character devices, block devices, named pipes, and
+named sockets.  Naturally the Hurd also support these.
+
+However, if you take a look at `hurd/io.defs` and `hurd/fs.defs`, you'll
+find that there are no RPCs that deal specifically with these types.
+Sure, you can get the type of the file through `io_stat` (among other
+things), but there are none that e.g.  lets you create a symbolic link.
+
+If you take a look at how glibc implements `symlink`, you'll notice
+that all it does is create a new file and sets its passive translator to
+`/hurd/symlink DEST`.  You can verify this yourself by creating a symlink
+with `ln -s foo bar` and print its translator with `showtrans bar`.
+
+This is how the other special files are implemented as well.  The header
+`hurd/paths.h` contains a list of paths that are used to implement
+special files:
+
+* `/hurd/symlink`
+* `/hurd/chrdev`
+* `/hurd/blkdev`
+* `/hurd/fifo`
+* `/hurd/ifsock`
+
+So all special files implemented through special purpose translators,
+right?  Well, actually there are no implementations of either `chrdev` or
+`blkdev` in the Hurd.  Instead these are implemented purely by /translator
+short-circuiting/.
+
+Translator short-circuiting is when a translator, instead of starting a
+passive translator, implements the functionality itself.  For instance,
+by continuing a file name look up by simply appending the path of a
+symlink without returning to the client.
+
+In fact the translators that are implemented are only used as a default
+implementation if the underlying translator does not implement the
+functionality itself.
+
+To make sure that you use one of these translators, you can start it as
+an active translator, or you can use a different path from the one in
+`hurd/path.h`, e.g. `settrans bar /hurd/./symlink foo`.
+
+The best example of how short-circuiting is implemented can be found
+in `libdiskfs`.  Notice how it detects if a translator is a special
+file in `diskfs_S_file_set_translator` and marks the node's `stat`
+structure.  And how it later checks the node's `stat` structure in
+`diskfs_S_dir_lookup` and handles special file types appropriately.