Head

GCC Code Coverage Report

Directory:	cvmfs/		Exec	Total	Coverage
File:	cvmfs/sync_union.h	Lines:	1	7	14.3 %
Date:	2019-02-03 02:48:13	Branches:	1	4	25.0 %


/**
 * This file is part of the CernVM File System
 *
 * This file defines a class to abstract information retrieval from
 * union file system components.
 *
 * There is a class UnionSync which is the base class for all
 * supported union file systems and provides support for the basic union fs
 * principals.
 *
 * There are three main principals, union file systems follow:
 *   1. Copy on Write
 *      read-only files in CVMFS will be copied up to an overlay
 *      volume on write access.
 *   2. Whiteout
 *      the union file system has to mark files as deleted, if you
 *      remove them from a read only file system
 *   3. Opaque Directories
 *      if you delete an entire directory from the read only file
 *      system and recreate it empty afterwards the union file system
 *      has to mark this directory as opaque to hide all old contents
 *
 * Furthermore, the union file system could create special files
 * for internal bookkeeping which should be ignored.
 *
 * Classes that derive from UnionSync implement the specifics of a concrete
 * union file system (e.g. AUFS, overlayfs).
 */

#ifndef CVMFS_SYNC_UNION_H_
#define CVMFS_SYNC_UNION_H_

#include <set>
#include <string>

#include "sync_item.h"
#include "util/shared_ptr.h"

namespace publish {

class AbstractSyncMediator;
class SyncMediator;

/**
 * Interface definition of repository synchronization based on
 * a union filesystem overlay on top of a mounted CVMFS volume.
 */
class SyncUnion {
 public:
  /**
   * @param rdonly_path the absolute path to the mounted cvmfs repository
   * @param union_path the absolute path to the mounted union file system volume
   * @param scratch_path the absolute path to the read write branch attached to
   *        the union file system
   * @param mediator a reference to a SyncMediator object used as bridge to
   *        the actual sync process
   */
  SyncUnion(AbstractSyncMediator *mediator, const std::string &rdonly_path,
            const std::string &union_path, const std::string &scratch_path);
  virtual ~SyncUnion() {}

  /**
   * Initialize internal state of the synchronisation. This needs to be called
   * before running anything else.
   * Note: should be up-called!
   */
  virtual bool Initialize();

  /**
   * Main routine, process scratch space
   */
  virtual void Traverse() = 0;

  virtual void PostUpload() { }

  /**
   * This produces a SyncItem and initialises it accordingly. This is the only
   * way client code can generate SyncItems to make sure it is always set up
   * properly (see SyncItem::SyncItem() for further details).
   * @param relative_parent_path  the directory path the SyncItem resides in
   * @param filename              file/directory name of directory entry
   * @param entry_type            type of the item in the union directory
   * @return                      a SyncItem object wrapping the dirent
   */
  SharedPtr<SyncItem> CreateSyncItem(const std::string &relative_parent_path,
                                     const std::string &filename,
                                     const SyncItemType entry_type) const;

  inline std::string rdonly_path() const { return rdonly_path_; }
  inline std::string union_path() const { return union_path_; }
  inline std::string scratch_path() const { return scratch_path_; }

  /**
   * Whiteout files may have special naming conventions.
   * This method "unmangles" them and retrieves the original file name
   * @param filename the filename as in the scratch directory
   * @return the original filename of the scratched out file in CVMFS repository
   */
  virtual std::string UnwindWhiteoutFilename(
      SharedPtr<SyncItem> entry) const = 0;

  /**
   * Union file systems use opaque directories to fully support rmdir
   * e.g:   $ rm -rf directory
   *        $ mkdir directory
   * This would produce an opaque directory whose contents are NOT merged with
   * the underlying directory in the read-only branch
   * @param directory the directory to check for opacity
   * @return true if directory is opaque, otherwise false
   */
  virtual bool IsOpaqueDirectory(SharedPtr<SyncItem> directory) const = 0;

  /**
   * Checks if given file is supposed to be whiteout.
   * These files indicate that a specific file has been deleted.
   * @param filename the filename to check
   * @return true if filename seems to be whiteout otherwise false
   */
  virtual bool IsWhiteoutEntry(SharedPtr<SyncItem> entry) const = 0;

  /**
   * Union file systems may use some special files for bookkeeping.
   * They must not show up in to repository and are ignored by the recursion.
   * Note: This needs to be up-called!
   * @param parent directory in which file resides
   * @param filename to decide whether to ignore or not
   * @return true if file should be ignored, othewise false
   */
  virtual bool IgnoreFilePredicate(const std::string &parent_dir,
                                   const std::string &filename);

  bool IsInitialized() const { return initialized_; }
  virtual bool SupportsHardlinks() const { return false; }

 protected:
  std::string rdonly_path_;
  std::string scratch_path_;
  std::string union_path_;

  AbstractSyncMediator *mediator_;

  /**
   * Allow for preprocessing steps before emiting any SyncItems from SyncUnion.
   * This can be overridden by sub-classes but should always be up-called. Typi-
   * cally this sets whiteout and opaque-directory flags or handles hardlinks.
   * @param entry  the SyncItem to be pre-processed
   *               (pointer parameter for google style guide compliance [1])
   * [1] https://google-styleguide.googlecode.com/svn/trunk/
   *             cppguide.html#Function_Parameter_Ordering
   */
  virtual void PreprocessSyncItem(SharedPtr<SyncItem> entry) const;

  /**
   * Callback when a regular file is found.
   * @param parent_dir the relative directory path
   * @param filename the filename
   */
  virtual void ProcessRegularFile(const std::string &parent_dir,
                                  const std::string &filename);

  /**
   * Callback when a directory is found.
   * @param parent_dir the relative directory path
   * @param dir_name the filename
   * @return true if file system traversal should branch into
   *         the given directory, false otherwise
   */
  virtual bool ProcessDirectory(const std::string &parent_dir,
                                const std::string &dir_name);
  virtual bool ProcessDirectory(SharedPtr<SyncItem> entry);
  virtual bool ProcessUnmaterializedDirectory(SharedPtr<SyncItem> entry);

  /**
   * Callback when a symlink is found.
   * @param parent_dir the relative directory path
   * @param link_name the filename
   */
  virtual void ProcessSymlink(const std::string &parent_dir,
                              const std::string &link_name);

  /**
   * Called if the file system traversal enters a directory for processing.
   * @param parent_dir the relative directory path.
   */
  virtual void EnterDirectory(const std::string &parent_dir,
                              const std::string &dir_name);

  /**
   * Called before the file system traversal leaves a processed directory.
   * @param parent_dir the relative directory path.
   */
  virtual void LeaveDirectory(const std::string &parent_dir,
                              const std::string &dir_name);

  /**
   * Callback when a character device is found
   * @param parent_dir the relative directory path
   * @param filename the filename
   */
  void ProcessCharacterDevice(const std::string &parent_dir,
                              const std::string &filename);

  /**
   * Callback when a block device is found
   * @param parent_dir the relative directory path
   * @param filename the filename
   */
  void ProcessBlockDevice(const std::string &parent_dir,
                          const std::string &filename);

  /**
   * Callback when a named pipe is found.
   * @param parent_dir the relative directory path
   * @param filename the filename
   */
  void ProcessFifo(const std::string &parent_dir, const std::string &filename);

  /**
   * Callback when a unix domain socket is found.
   * @param parent_dir the relative directory path
   * @param filename the filename
   */
  void ProcessSocket(const std::string &parent_dir,
                     const std::string &filename);

  /**
   * Called to actually process the file entry.
   * @param entry the SyncItem corresponding to the union file to be processed
   */
  void ProcessFile(SharedPtr<SyncItem> entry);

 private:
  bool initialized_;
};  // class SyncUnion

}  // namespace publish

#endif  // CVMFS_SYNC_UNION_H_


Generated by: GCOVR (Version 4.1)

Line	Branch	Exec	Source
1			/**
2			* This file is part of the CernVM File System
3			*
4			* This file defines a class to abstract information retrieval from
5			* union file system components.
6			*
7			* There is a class UnionSync which is the base class for all
8			* supported union file systems and provides support for the basic union fs
9			* principals.
10			*
11			* There are three main principals, union file systems follow:
12			* 1. Copy on Write
13			* read-only files in CVMFS will be copied up to an overlay
14			* volume on write access.
15			* 2. Whiteout
16			* the union file system has to mark files as deleted, if you
17			* remove them from a read only file system
18			* 3. Opaque Directories
19			* if you delete an entire directory from the read only file
20			* system and recreate it empty afterwards the union file system
21			* has to mark this directory as opaque to hide all old contents
22			*
23			* Furthermore, the union file system could create special files
24			* for internal bookkeeping which should be ignored.
25			*
26			* Classes that derive from UnionSync implement the specifics of a concrete
27			* union file system (e.g. AUFS, overlayfs).
28			*/
29
30			#ifndef CVMFS_SYNC_UNION_H_
31			#define CVMFS_SYNC_UNION_H_
32
33			#include <set>
34			#include <string>
35
36			#include "sync_item.h"
37			#include "util/shared_ptr.h"
38
39			namespace publish {
40
41			class AbstractSyncMediator;
42			class SyncMediator;
43
44			/**
45			* Interface definition of repository synchronization based on
46			* a union filesystem overlay on top of a mounted CVMFS volume.
47			*/
48			class SyncUnion {
49			public:
50			/**
51			* @param rdonly_path the absolute path to the mounted cvmfs repository
52			* @param union_path the absolute path to the mounted union file system volume
53			* @param scratch_path the absolute path to the read write branch attached to
54			* the union file system
55			* @param mediator a reference to a SyncMediator object used as bridge to
56			* the actual sync process
57			*/
58			SyncUnion(AbstractSyncMediator *mediator, const std::string &rdonly_path,
59			const std::string &union_path, const std::string &scratch_path);
60	✗✗✗✓	1	virtual ~SyncUnion() {}
61
62			/**
63			* Initialize internal state of the synchronisation. This needs to be called
64			* before running anything else.
65			* Note: should be up-called!
66			*/
67			virtual bool Initialize();
68
69			/**
70			* Main routine, process scratch space
71			*/
72			virtual void Traverse() = 0;
73
74			virtual void PostUpload() { }
75
76			/**
77			* This produces a SyncItem and initialises it accordingly. This is the only
78			* way client code can generate SyncItems to make sure it is always set up
79			* properly (see SyncItem::SyncItem() for further details).
80			* @param relative_parent_path the directory path the SyncItem resides in
81			* @param filename file/directory name of directory entry
82			* @param entry_type type of the item in the union directory
83			* @return a SyncItem object wrapping the dirent
84			*/
85			SharedPtr<SyncItem> CreateSyncItem(const std::string &relative_parent_path,
86			const std::string &filename,
87			const SyncItemType entry_type) const;
88
89			inline std::string rdonly_path() const { return rdonly_path_; }
90			inline std::string union_path() const { return union_path_; }
91			inline std::string scratch_path() const { return scratch_path_; }
92
93			/**
94			* Whiteout files may have special naming conventions.
95			* This method "unmangles" them and retrieves the original file name
96			* @param filename the filename as in the scratch directory
97			* @return the original filename of the scratched out file in CVMFS repository
98			*/
99			virtual std::string UnwindWhiteoutFilename(
100			SharedPtr<SyncItem> entry) const = 0;
101
102			/**
103			* Union file systems use opaque directories to fully support rmdir
104			* e.g: $ rm -rf directory
105			* $ mkdir directory
106			* This would produce an opaque directory whose contents are NOT merged with
107			* the underlying directory in the read-only branch
108			* @param directory the directory to check for opacity
109			* @return true if directory is opaque, otherwise false
110			*/
111			virtual bool IsOpaqueDirectory(SharedPtr<SyncItem> directory) const = 0;
112
113			/**
114			* Checks if given file is supposed to be whiteout.
115			* These files indicate that a specific file has been deleted.
116			* @param filename the filename to check
117			* @return true if filename seems to be whiteout otherwise false
118			*/
119			virtual bool IsWhiteoutEntry(SharedPtr<SyncItem> entry) const = 0;
120
121			/**
122			* Union file systems may use some special files for bookkeeping.
123			* They must not show up in to repository and are ignored by the recursion.
124			* Note: This needs to be up-called!
125			* @param parent directory in which file resides
126			* @param filename to decide whether to ignore or not
127			* @return true if file should be ignored, othewise false
128			*/
129			virtual bool IgnoreFilePredicate(const std::string &parent_dir,
130			const std::string &filename);
131
132			bool IsInitialized() const { return initialized_; }
133			virtual bool SupportsHardlinks() const { return false; }
134
135			protected:
136			std::string rdonly_path_;
137			std::string scratch_path_;
138			std::string union_path_;
139
140			AbstractSyncMediator *mediator_;
141
142			/**
143			* Allow for preprocessing steps before emiting any SyncItems from SyncUnion.
144			* This can be overridden by sub-classes but should always be up-called. Typi-
145			* cally this sets whiteout and opaque-directory flags or handles hardlinks.
146			* @param entry the SyncItem to be pre-processed
147			* (pointer parameter for google style guide compliance [1])
148			* [1] https://google-styleguide.googlecode.com/svn/trunk/
149			* cppguide.html#Function_Parameter_Ordering
150			*/
151			virtual void PreprocessSyncItem(SharedPtr<SyncItem> entry) const;
152
153			/**
154			* Callback when a regular file is found.
155			* @param parent_dir the relative directory path
156			* @param filename the filename
157			*/
158			virtual void ProcessRegularFile(const std::string &parent_dir,
159			const std::string &filename);
160
161			/**
162			* Callback when a directory is found.
163			* @param parent_dir the relative directory path
164			* @param dir_name the filename
165			* @return true if file system traversal should branch into
166			* the given directory, false otherwise
167			*/
168			virtual bool ProcessDirectory(const std::string &parent_dir,
169			const std::string &dir_name);
170			virtual bool ProcessDirectory(SharedPtr<SyncItem> entry);
171			virtual bool ProcessUnmaterializedDirectory(SharedPtr<SyncItem> entry);
172
173			/**
174			* Callback when a symlink is found.
175			* @param parent_dir the relative directory path
176			* @param link_name the filename
177			*/
178			virtual void ProcessSymlink(const std::string &parent_dir,
179			const std::string &link_name);
180
181			/**
182			* Called if the file system traversal enters a directory for processing.
183			* @param parent_dir the relative directory path.
184			*/
185			virtual void EnterDirectory(const std::string &parent_dir,
186			const std::string &dir_name);
187
188			/**
189			* Called before the file system traversal leaves a processed directory.
190			* @param parent_dir the relative directory path.
191			*/
192			virtual void LeaveDirectory(const std::string &parent_dir,
193			const std::string &dir_name);
194
195			/**
196			* Callback when a character device is found
197			* @param parent_dir the relative directory path
198			* @param filename the filename
199			*/
200			void ProcessCharacterDevice(const std::string &parent_dir,
201			const std::string &filename);
202
203			/**
204			* Callback when a block device is found
205			* @param parent_dir the relative directory path
206			* @param filename the filename
207			*/
208			void ProcessBlockDevice(const std::string &parent_dir,
209			const std::string &filename);
210
211			/**
212			* Callback when a named pipe is found.
213			* @param parent_dir the relative directory path
214			* @param filename the filename
215			*/
216			void ProcessFifo(const std::string &parent_dir, const std::string &filename);
217
218			/**
219			* Callback when a unix domain socket is found.
220			* @param parent_dir the relative directory path
221			* @param filename the filename
222			*/
223			void ProcessSocket(const std::string &parent_dir,
224			const std::string &filename);
225
226			/**
227			* Called to actually process the file entry.
228			* @param entry the SyncItem corresponding to the union file to be processed
229			*/
230			void ProcessFile(SharedPtr<SyncItem> entry);
231
232			private:
233			bool initialized_;
234			}; // class SyncUnion
235
236			} // namespace publish
237
238			#endif // CVMFS_SYNC_UNION_H_