HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
PDG_CustomHandlers.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * COMMENTS:
7  */
8 
9 #ifndef PDG_CUSTOM_HANDLERS_H
10 #define PDG_CUSTOM_HANDLERS_H
11 
12 #include "PDG_API.h"
13 
14 #include "PDG_File.h"
15 #include "PDG_WorkItemTypes.h"
16 
17 #include <UT/UT_Array.h>
18 #include <UT/UT_NonCopyable.h>
19 #include <UT/UT_StringHolder.h>
20 #include <UT/UT_StringMap.h>
21 #include <UT/UT_StringSet.h>
22 #include <UT/UT_UniquePtr.h>
23 
24 struct PDG_CookOptions;
25 class PDG_GraphContext;
26 class PDG_Node;
27 class PDG_Scheduler;
28 class PDG_WorkItem;
29 
30 class UT_FileStat;
31 
32 /*
33  * Table of custom, user-authorable handlers for globally controlling the
34  * behavior of file caching, dirtying and work item regeneration
35  */
37 {
38 public:
39  /// Return result for custom cache handlers
41  {
42  /// The custom handler has determined that the file was not cached
44 
45  /// The custom handler has determined that the file was found
47 
48  /// The custom handler does not wish to handle the file
49  eCacheSkip
50  };
51 
52  /// Enunmerations of different work item regeneration levels that
53  /// can returned by the correpsonding handler.
55  {
56  /// Normal work item regeneration, including both attributes and
57  /// cache file invalidation.
59 
60  /// Regenerate attributes but leave cache files as-is
62 
63  /// Do not regenerate work item attributes nor invalidate cache files
65 
66  /// Ignore the handler
68  };
69 
70  /// Enumeration of different file transfer handle results.
72  {
73  /// The custom handler failed to transfer the file
75 
76  /// The custom handler successfully transfered the file
78 
79  /// The custom handler chose not to transfer the file, and it should
80  /// be handled by the next handler in the list or the default.
82 
83  /// The custom handler determined that the file was cached/already
84  /// transfered, and no further attempts should be made to copy it
85  eTransferCached
86  };
87 
88  /// Enumeration of different levels of dirty handler
90  {
91  /// The custom dirty handler runs for any dirtied work items
93 
94  /// The custom dirty handler runs only for work items that are
95  /// being deleted
97 
98  /// The custom dirty handler runs only for work itesm that are
99  /// being deleted, and have their outputs removed from disk
100  eDirtyDeleteFiles
101  };
102 
103  /// Custom return type for a file transfer operation, which includes both
104  /// a status enum and a mod time/cache id
106  {
107  /// The transfer result, e.g. failed or cached
109 
110  /// the user-defined cache id
112  };
113 
114  /// Custom return type a file stat operation, which includes both a
115  /// hash-type value and a file size.
117  {
118  /// The hash/mod time of the file
120 
121  /// The size of the file
123  };
124 
125 public:
126 
127  /// Custom functor for checking if a file is cached. These are keyed
128  /// on the tag associated with the file.
130  {
131  public:
133  virtual ~CacheHandler() {}
135 
136  virtual CacheResult checkCached(
137  const UT_StringHolder& local_path,
138  const PDG_File& file,
139  const PDG_WorkItem* work_item) const = 0;
140  };
141 
142  /// Custom functor for stating a file and returning a size/hash
144  {
145  public:
147  virtual ~StatHandler() {}
148  UT_NON_COPYABLE(StatHandler)
149 
150  virtual StatPair statFile(
151  const UT_StringHolder& local_path,
152  const PDG_File& file,
153  const PDG_WorkItem* work_item) const = 0;
154  };
155 
156  /// Custom functor for handling dirtied work items, and possibly output
158  {
159  public:
162  const UT_ArrayStringSet& schedulers,
163  const UT_ArrayStringSet& nodes,
164  bool requires_outputs,
165  bool global)
166  : myType(type)
167  , mySchedulerFilter(schedulers)
168  , myNodeFilter(nodes)
169  , myRequiresOutputs(requires_outputs)
170  , myIsGlobal(global) {}
171  virtual ~DirtyHandler() {}
172  UT_NON_COPYABLE(DirtyHandler)
173 
174  virtual bool handleDirty(
175  const PDG_WorkItem* work_item,
176  const PDG_File::Set& files) const = 0;
177 
178  bool matchScheduler(const PDG_Scheduler* scheduler);
179  bool matchNode(const PDG_Node* node);
180 
181  inline DirtyHandlerType type() const
182  { return myType; }
183  inline bool requiresOutputs() const
184  { return myRequiresOutputs; }
185  inline bool isGlobal() const
186  { return myIsGlobal; }
187 
188  private:
189  UT_ArrayStringSet mySchedulerFilter;
190  UT_ArrayStringSet myNodeFilter;
191  DirtyHandlerType myType;
192  bool myRequiresOutputs;
193  bool myIsGlobal;
194  };
195 
196  /// Custom functor for determining if a node should regenerate
197  /// work items
199  {
200  public:
202  virtual ~RegenerationHandler() {}
204 
205  virtual RegenerateResult shouldRegenerate(
206  const PDG_Node*,
207  const PDG_WorkItemArray&) const = 0;
208  };
209 
210  /// Custom functor for transfering a file from the local machine to
211  /// remote directory associated with the scheduler
213  {
214  public:
215  TransferHandler(bool use_mod_time)
216  : myUseModTime(use_mod_time) {}
217  virtual ~TransferHandler() {}
218  UT_NON_COPYABLE(TransferHandler)
219 
220  virtual TransferPair transferFile(
221  const UT_StringHolder& local_path,
222  const UT_StringHolder& remote_path,
223  const PDG_File& file,
224  const PDG_WorkItem* work_item,
225  const PDG_Scheduler* scheduler,
226  exint last_update) const = 0;
227  inline bool useModTime() const
228  { return myUseModTime; }
229 
230  private:
231  bool myUseModTime;
232  };
233 
234  /// Custom handler functor for running pre-flight logic before a cook
236  {
237  public:
238  PreflightHandler(bool is_generate_graph)
239  : myIsGenerateGraph(is_generate_graph) {}
240  virtual ~PreflightHandler() {}
242 
243  virtual bool preflight(
244  PDG_GraphContext* context,
245  const PDG_CookOptions& options,
246  UT_WorkBuffer& errors) const = 0;
247  inline bool isGenerateGraph() const
248  { return myIsGenerateGraph; }
249 
250  private:
251  bool myIsGenerateGraph;
252  };
253 
254  /// Unique pointer to a custom cache handler
256 
257  /// Cache handler map
259 
260 
261  /// Unique pointer to a custom stat handler
263 
264  /// State handler map
266 
267 
268  /// Unique pointer to a custom delete handler
270 
271  /// Delete handler map
273 
274 
275  /// Unique pointer to a custom regeneration handler
277 
278  /// Regeneration handler array
280 
281 
282  /// Unique pointer to a custom transfer handler
284 
285  /// Transfer handler array
287 
288 
289  /// Unique pointer to a custom preflight handler
291 
292  /// Preflight handler array
294 
295 public:
296  /// Returns the map of cache handlers, tag -> handler
298  { return myCacheHandlers; }
299 
300  /// Returns the map of stat handlers, tag -> handler
302  { return myStatHandlers; }
303 
304  /// Returns the map of transfer handlers, tag -> handler
306  { return myTransferHandlers; }
307 
308  /// Returns the array of dirty handlers
310  { return myDirtyHandlers; }
311 
312  // Returns the array of regeneration handlers
314  { return myRegenHandlers; }
315 
316  // Returns the array of preflight handlers
318  { return myPreflightHandlers; }
319 
320 
321  /// Adds a custom tag prefix -> cache handler mapping. Returns true if an
322  /// existing entry was replaced.
323  bool addCacheHandler(
324  const UT_StringHolder& tag,
325  CacheHandler* handler);
326 
327  /// Adds a custom tag prefix -> hash handler mapping. Returns true if an
328  /// existing entry was replaced.
329  bool addStatHandler(
330  const UT_StringHolder& tag,
331  StatHandler* handler);
332 
333  /// Adds a custom delete handler.
334  void addDirtyHandler(DirtyHandler* handler);
335 
336  /// Adds a custom regeneration handler.
337  void addRegenerationHandler(
338  RegenerationHandler* handler);
339 
340  /// Adds a custom transfer handler.
341  bool addTransferHandler(
342  const UT_StringHolder& tag,
343  TransferHandler* handler);
344 
345  /// Adds a custom preflight handler.
346  void addPreflightHandler(
347  PreflightHandler* handler);
348 
349  /// Returns true if there are any custom dirty handlers registered
350  bool hasDirtyHandlers(
351  DirtyHandlerType type) const;
352 
353  /// Clears all cache and delete handlers
354  void clearHandlers();
355 
356  /// Checks if a given file path is cached
357  CacheResult handleCache(
358  const UT_StringHolder& local_path,
359  const PDG_File& file,
360  const PDG_WorkItem* work_item) const;
361 
362  /// Returns the hash/mod time of the file
363  StatPair handleStat(
364  const UT_StringHolder& local_path,
365  const PDG_File& file,
366  const PDG_WorkItem* work_item) const;
367 
368  /// Called before a dirty w/ deleted outputs, in order to run global delete
369  /// handlers
370  void handleDirtyGlobal(
371  bool delete_items,
372  bool remove_outputs) const;
373 
374  /// Called when a work item should delete files, and runs any custom
375  /// handlers that match the item
376  bool handleDirty(
377  const PDG_WorkItem* work_item,
378  const PDG_File::Set& files,
379  bool delete_items,
380  bool remove_outputs) const;
381 
382  /// Called when a node is going to regenerate work items, to see if it
383  /// should.
384  RegenerateResult handleRegenerate(
385  PDG_Node* node,
386  const PDG_WorkItemArray& items);
387 
388  /// Called when a file needs to be transfered to the working directory
389  /// of a scheduler
390  TransferPair handleTransfer(
391  const UT_FileStat& local_stat,
392  const UT_StringHolder& local_path,
393  const UT_StringHolder& remote_path,
394  const PDG_File& file,
395  const PDG_WorkItem* work_item,
396  const PDG_Scheduler* scheduler,
397  exint last_update) const;
398 
399  /// Called when the graph run preflight logic, and returns false if any
400  /// of the handlers fail.
401  bool handlePreflight(
402  const PDG_CookOptions& options,
403  PDG_GraphContext* context,
404  UT_WorkBuffer& errors);
405 
406 protected:
407  friend class PDG_TypeRegistry;
408 
409  /// Constructs a new instance of the table
411 private:
412  bool matchDirtyHandler(
413  const DirtyHandlerPtr& handler,
414  const PDG_File::Set& files,
415  bool global,
416  bool delete_items,
417  bool remove_outputs) const;
418 
419 private:
420  // Map of tag prefix -> custom cache handler
421  CacheHandlerMap myCacheHandlers;
422 
423  // Map of tag prefix -> custom hash handler
424  StatHandlerMap myStatHandlers;
425 
426  // Map of tag prefix -> custom transfer handler
427  TransferHandlerMap myTransferHandlers;
428 
429  // Array of delete handlers
430  DirtyHandlerArray myDirtyHandlers;
431 
432  // Array of regeneration handlers
433  RegenHandlerArray myRegenHandlers;
434 
435  // Array of preflight handlers
436  PreflightHandlerArray myPreflightHandlers;
437 
438  // Set to true when preflight handlers begin evaluating, to avoid
439  // recursive cooks triggering handlers again.
440  bool myIsHandlingPreflight;
441 };
442 
443 #endif
The custom handler failed to transfer the file.
*get result *(waiting if necessary)*A common idiom is to fire a bunch of sub tasks at the and then *wait for them to all complete We provide a helper class
Definition: thread.h:623
UT_UniquePtr< StatHandler > StatHandlerPtr
Unique pointer to a custom stat handler.
UT_UniquePtr< CacheHandler > CacheHandlerPtr
Unique pointer to a custom cache handler.
#define PDG_API
Definition: PDG_API.h:23
int64 exint
Definition: SYS_Types.h:125
const PreflightHandlerArray & preflightHandlers() const
Custom functor for handling dirtied work items, and possibly output.
UT_UniquePtr< RegenerationHandler > RegenHandlerPtr
Unique pointer to a custom regeneration handler.
PreflightHandler(bool is_generate_graph)
The custom handler has determined that the file was found.
std::unique_ptr< T, Deleter > UT_UniquePtr
A smart pointer for unique ownership of dynamically allocated objects.
Definition: UT_UniquePtr.h:39
const TransferHandlerMap & transferHandlers() const
Returns the map of transfer handlers, tag -> handler.
The custom handler has determined that the file was not cached.
const DirtyHandlerArray & dirtyHandlers() const
Returns the array of dirty handlers.
PDG_File::Hash myHash
The hash/mod time of the file.
const CacheHandlerMap & cacheHandlers() const
Returns the map of cache handlers, tag -> handler.
UT_UniquePtr< DirtyHandler > DirtyHandlerPtr
Unique pointer to a custom delete handler.
int64 Hash
The file hash/modtime type.
Definition: PDG_File.h:39
#define UT_NON_COPYABLE(CLASS)
Define deleted copy constructor and assignment operator inside a class.
DirtyHandler(DirtyHandlerType type, const UT_ArrayStringSet &schedulers, const UT_ArrayStringSet &nodes, bool requires_outputs, bool global)
TransferResult myResult
The transfer result, e.g. failed or cached.
DirtyHandlerType
Enumeration of different levels of dirty handler.
const RegenHandlerArray & regenerationHandlers() const
Custom handler functor for running pre-flight logic before a cook.
Custom functor for stating a file and returning a size/hash.
exint mySize
The size of the file.
The custom dirty handler runs for any dirtied work items.
Regenerate attributes but leave cache files as-is.
Do not regenerate work item attributes nor invalidate cache files.
exint myCacheID
the user-defined cache id
The custom handler successfully transfered the file.
UT_UniquePtr< PreflightHandler > PreflightHandlerPtr
Unique pointer to a custom preflight handler.
type
Definition: core.h:1059
const StatHandlerMap & statHandlers() const
Returns the map of stat handlers, tag -> handler.
TransferResult
Enumeration of different file transfer handle results.
UT_UniquePtr< TransferHandler > TransferHandlerPtr
Unique pointer to a custom transfer handler.
CacheResult
Return result for custom cache handlers.