From da0fb43a3b2cbb47bde840fbdb1433208278a7a8 Mon Sep 17 00:00:00 2001 From: scolobb Date: Sat, 1 Nov 2008 06:35:47 +0000 Subject: --- hurd/libnetfs.mdwn | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'hurd/libnetfs.mdwn') diff --git a/hurd/libnetfs.mdwn b/hurd/libnetfs.mdwn index 41f39521..404ae3f0 100644 --- a/hurd/libnetfs.mdwn +++ b/hurd/libnetfs.mdwn @@ -10,7 +10,7 @@ is included in the section entitled #libnetfs -WHAT IS THIS +##What This Is This document is an attempt at a short overview of the main concepts used in the process of development of translators using @@ -20,7 +20,7 @@ required callbacks (for this take a look at will **not** find a complete example of code either (usually, *unionfs* is suggested as an example) -WHAT IS LIBNETFS +##What libnetfs Is *libnetfs* is a Hurd library used in writing translators providing some virtual directory structures. For example, if you would like to @@ -37,7 +37,7 @@ make an archive look unpacked). As different from *libtrivfs*, using *libnetfs*, you can show to your clients not just a single file, but a whole directory tree. -HOW IT WORKS: SHORT DESCRIPTION +##How It Works: Short Description With the aid of *libnetfs* a translator (supposedly) publishes a directory tree. All lookups in this directory tree are directed to the @@ -49,13 +49,13 @@ implement the required functionality in the corresponding callback or just return an appropriate error code (for example, EOPNOTSUPP), if the callback is compulsory. -THE MAIN CONCEPTS: NODES +##The Main Concepts: Nodes The most fundamental thing to understand about *libnetfs* is the notion of a **node**. Nearly always there are two types of nodes in a *libnetfs*-based translator: -* Generic **node**, defined in **. This node contains +* Generic **node**, defined in *<hurd/netfs.h>*. This node contains information read and written by the programmer (like field *nn_stat*), as well as some internal information (like fields *references* and *transbox*). Of course, the programmer is free to @@ -71,7 +71,7 @@ operation. To some extent of certainty, a *libnetfs* node can be perceived similarly to a filesystem node -- the building-brick out of which everything is composed. -As it can be seen from the definition in **, a reference +As it can be seen from the definition in *<hurd/netfs.h>*, a reference to a netnode is stored in each generic node. In a way, a netnode can be perceived as the custom attachment to the information contained in a generic node. The link between these is quite strong. At first this @@ -119,10 +119,10 @@ to share netnodes, one would not be able to store additional information per a *libnetfs* node, and this is quite a serious problem in most practical problems. -WHY A LIBNETFS NODE IS NOT QUITE A FILESYSTEM NODE +##Why a libnetfs Node Is Not Quit a Filesystem Node The most demonstrative argument in this case is the definition of -*struct node* in **. If you try to find in this +*struct node* in *<hurd/netfs.h>*. If you try to find in this definition some reference to other generic node called *parent*, or an array of references called *children* (which would be quite classical for a member of a hierarchy), you will fail. There are fields *next* @@ -148,7 +148,7 @@ result. Therefore, it is not quite right to perceive *libnetfs* nodes as filesystem nodes. Instead, the focus of attention should stay upon light nodes. -HOW IT WORKS: A MORE VERBOSE DESCRIPTION +##How It Wors: A More Verbose Description At first let us see how the a *libnetfs*-based translator responds to lookup requests. At the beginning the *netfs_attempt_lookup* callback @@ -219,14 +219,14 @@ parameters to the corresponding *io_read* and *io_write* functions. While browsing the code of very many *libnetfs*-based translators, you might notice that they define callbacks starting with -*netfs_S_*. Usually a name similar to that of one of the file -management function follows (like netfs_S_*dir_lookup). These +*netfs_S_*. Usually a name similar to that of one of the file +management function follows (like netfs_S_*dir_lookup*). These callbacks are triggered when the corresponding functions are called on files shown by the translator. Such translators override parts of the core functionality provided by *libnetfs* to achieve better performance or to solve specific problems. -SYNCHRONIZATION IS CRUCIAL +##Synchronization is Crucial A *libnetfs* programmer shall always keep in mind that, as different from *libtrivfs*-based translators, *libnetfs*-based translators are @@ -235,7 +235,7 @@ incorporates a lock. Moreover, each light node usually contains a lock, too. This happens because *libnetfs* nodes and light nodes are loosely coupled and are often processed separately. -NODE CACHE +##Node Cache Most of *libnetfs* translators organize a *node cache*. However, this structure is not a real cache. The idea is to hold some control over @@ -254,7 +254,7 @@ overgrown, the nodes located at the tail of the list are removed from the cache and the references to them are dropped. This triggers their destruction (undertaken by *libnetfs*). -WHAT FILES ARE USUALLY CREATED +##What Files Are Usually Created If you take into a look at the sources *ftpfs* or *unionfs* you will notice files with names similar to the following: @@ -270,10 +270,10 @@ notice files with names similar to the following: * options.{c,h} -- here the option parsing mechanism is usually placed. Argp parsers are implemented here. -* <*translator_name*>.{c,h}, netfs.c -- the implementation of *netfs_\** +* <*translator_name*>.{c,h}, netfs.c -- the implementation of *netfs_\** callbacks will most probably lie in these files. -WHAT NETNODES AND LIGHT NODES USUALLY CONTAIN +##What Netnodes and Light Nodes Usually Contain A **netnode** usually contains a reference to a light node, some flags describing the state of the associated generic *libnetfs* node, and @@ -289,7 +289,7 @@ hierarchical way, they contain a reference to their parent, a reference to their first child, and references to their siblings (usually not very descriptively called *next* and *prevp*). -THE END +##The End I very much hope this piece of text was at least a little helpful. Here I tried to explain the things which I understood least -- cgit v1.2.3