= Directories =  Filesystem directories contain collections of files, other directories, along with other filesystem objects. Directories can be listed, permitting filesystem clients to peruse the contents of each directory. However, the act of listing a directory may impose certain constraints on the operations being conducted on the directory during the listing process.  Operations that affect directory contents include the following:   * Creating a new object  * Removing an object  * Moving an object out of the directory  * Moving an object into the directory  It is conceivable that for some filesystems, these operations will not be able to rely on directly modifying the directory since a listing operation may be in progress. Consequently, a number of rules would be imposed for such filesystems. It appears that Ext2-based filesystems accessed via libext2fs do not require such rules to be applied outside the library due to the design of the filesystem structures and the behaviour of the library itself.  == Providers ==  Providers of filesystem objects are created when at least one filesystem client is accessing such an object, with the object regarded as being '''open'''. By definition, a provider will exist until all clients have closed or discarded their means of accessing the object.  An object is regarded as '''accessible''' if it can still be opened by filesystem clients. Where an object has been removed, it will no longer be accessible since clients should not be able to see the object in the filesystem any more. (The actual filesystem residing in storage may not have been updated for such a removal, this being the eventual outcome of a removal operation.)  Providers can be regarded as '''accessible''' if they maintain access to objects that are open and accessible. Clients opening objects will only gain access to accessible providers. Providers can become inaccessible if an object is removed even if the object (and its provider) is still open.  Initially, providers will correspond to objects resident in the stored filesystem. Thus, looking up an object using its path will involve the filesystem, yielding a file identifier that can be used to map to a provider.  {{{ def get_provider_from_filesystem(path):     fileid = opening.get_fileid(path)      if not fileid:         return error      return find_provider(fileid) }}}  However, providers may not always immediately correspond to objects resident in the stored filesystem. Where an object is created but cannot be immediately registered in the contents of a directory, it must be registered separately and attempts to open this object must consult this separate mapping of filenames to providers.  {{{ def get_provider(path):     provider = find_created_provider(path)      if provider:         return provider      return get_provider_from_filesystem(path) }}}  Providers that are inaccessible need to be retained until they are closed. However, since they are no longer accessible, they should not be available to the provider lookup operations.  When providers are closed, they are removed from any mapping in which they could be found. Inaccessible providers that have been retained outside the identifier or filename mappings will represent objects that should be removed from their parent directory. Accessible providers retained by the mappings will represent objects that should be created in their parent directory.  Whether object removal or creation will occur depends on whether the parent directory is able to safely perform these operations concurrently with other operations (such as servicing a listing operation) or whether such operations will need to be deferred until they can be safely performed.  == Object Removal ==  Filesystem object removal involves obtaining any provider of the object. Where a provider can be obtained, it will be made inaccessible and removal will be requested. The actual object will not be removed at least until it is closed because it may still receive and provide data. (Unlinking open files is a feature of Unix systems.)  Where a provider cannot be obtained, an attempt will be made to obtain the parent directory provider, and if this succeeds, it indicates that the directory is being accessed and must therefore be notified of the intention to eventually remove the object concerned.  Without any provider of the object, and where no directory provider can be obtained, the object can be immediately removed from the filesystem.  {{{ def remove_object(path):     provider = get_provider(path)      if provider:         return make_provider_inaccessible(provider)      dirname, basename = split(path)     directory_provider = get_provider(dirname)      if directory_provider:         return directory_provider.remove_pending(basename)      return filesystem.remove_object(path) }}}  It should be noted that with no accessible provider, any attempt to create a file with the same name as a removed file should cause a new "version" of the file to be created.  == Object Creation ==  Filesystem object creation occurs when no existing provider can be found for a named object and where creation is requested. Any new object will be accessible and remain so until or unless it is removed.  Whether an object is created in the filesystem storage depends on whether the parent directory is being used.  If a parent directory is not being used, the object can be registered in its proper location in the filesystem itself, yielding a file identifier.  If a parent directory is being used, the object cannot be immediately registered in its proper location, but since data may still need to be written to storage, a temporary location is employed, yielding a file identifier.  For an object created in a temporary location, a temporary mapping from the path of the object to the provider is established, with the parent directory being notified of the pending object creation.  {{{ def create_object(path):     provider = get_provider(path)      if provider:         return error      dirname, basename = split(path)     directory_provider = get_provider(dirname)      if directory_provider:         provider = make_provider(get_temporary_location(path))         directory_provider.create_pending(provider)         return register_created_provider(path, provider)      provider = make_provider(path)     return register_provider(provider) }}}  == Created Providers ==  Created providers are retained by the registry until their files can be committed to the filesystem in the desired location.  The `register_created_provider` operation establishes a mapping from a path to a provider that can be queried using the `find_created_provider` operation.  Created providers are deregistered when they are closed. This will occur when the parent directory of the file to be committed is closed. At that time, the created file will be moved from its temporary location to the desired location.  == Inaccessible Providers ==  Inaccessible providers are retained by the registry until they are closed.  Where the provided file resides in a non-temporary location, closure will occur when the parent directory of the provided file is closed, this having obstructed the removal of the file. At that time, the provided file will be removed.  Where the provided file resides in a temporary location, closure will not be obstructed by any directory and will cause the file to be removed immediately.  == Directory Provider Closure ==  A critical event that typically initiates housekeeping work for created and removed files is the closure of the parent directory of those files.  Directory providers support the `create_pending` and `remove_pending` operations that register the details of affected files. When closure occurs, the provider will contact the registry to initiate the necessary work to relocate created files and to remove files.       Where an object provider is notified of pending removal, it will initiate   removal of the actual object upon closure, checking for an active parent   provider.    Where a parent provider is notified of pending removal, it will initiate   removal of the actual object upon closure, checking for an active object   provider.    Object opening logic would need to be adjusted. Consider the case where a   file is removed but still open.      Any attempt to open a file with the same name must ignore the original and     open a new file of that name which would be stored elsewhere until such     time as the original is actually removed from its location.      This new file might have a different identifier since the original file     would still exist and retain the identifier.      Any such new, but uncommitted, file must be accessible by other clients     attempting to open a file of that name. However, removal operations must     also be possible, making this version of the open file also unaccessible     to new opening clients.      Therefore, any providers used by opening clients must only refer to a     version of a file that is pending removal if no other version has been     created. Once a new version has been created, any provider pending removal     must be relegated to a separate collection.      Storage of new versions of files could be confined to special directories     that are hidden from clients.      The opening logic would be as follows:        provider = find_provider(path)        if provider:           if provider.pending_removal():               relegate(provider)               provider = create_provider(path, hidden=True)       else:           provider = create_provider(path, hidden=False)        # Have provider.        return provider.make_resource()      A provider would normally be obtained by consulting the filesystem     implementation. However, new versions of files replacing ones pending     removal will reside in locations that are different to the intended     location of the file. Consequently, the registry needs to maintain its own     mapping of paths to providers for such file versions.      The opportunity to remove a file definitively arises when the following     conditions are satisfied:        * The parent directory is not open in some way       * The original provider for the file is no longer open      For new versions of a removed file that have themselves been marked as     pending removal, their closure is sufficient to remove their filesystem     resources.      However, the registry must maintain a path entry for any active version     of a removed file until that version is closed. Thus, the following     conditions apply:        * The parent directory (of the original file) is not open in some way       * The provider of the new version is no longer open      It will not be generally possible to open the hidden directory containing     new file versions. Therefore, the transfer of the file to its intended     location will not risk interfering with any operations on the hidden     directory.