PDG_Types.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * COMMENTS:
 */

#ifndef __PDG_TYPES_H__
#define __PDG_TYPES_H__

#include <PDGT/PDGT_BaseType.h>
#include <PDGT/PDGT_RegisteredType.h>
#include <PDGT/PDGT_TypeInstance.h>

#include <UT/UT_Array.h>
#include <UT/UT_ArrayMap.h>
#include <UT/UT_ArraySet.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_Map.h>
#include <UT/UT_Set.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_Optional.h>
#include <UT/UT_UniquePtr.h>

#include <SYS/SYS_Types.h>

#include <utility>

class PDG_BatchWorkItem;
class PDG_Dependency;
class PDG_Node;
class PDG_NodeCallback;
class PDG_Port;
class PDG_Scheduler;
class PDG_Service;
class PDG_WorkItem;
class PDG_WorkItemData;

/// Type defs for registered type objects
using PDG_DependencyPtr         = UT_SharedPtr<PDG_Dependency>;
using PDG_NodeCallbackPtr       = UT_SharedPtr<PDG_NodeCallback>;
using PDG_SchedulerPtr          = UT_SharedPtr<PDG_Scheduler>;
using PDG_ServicePtr            = UT_SharedPtr<PDG_Service>;
using PDG_WorkItemDataPtr       = UT_SharedPtr<PDG_WorkItemData>;

/// Type defs for unique work item IDs
using PDG_WorkItemID            = exint;
using PDG_WorkItemIDArray       = UT_Array<PDG_WorkItemID>;
using PDG_WorkItemIDSet         = UT_ArraySet<PDG_WorkItemID>;
using PDG_WorkItemIDMap         = UT_ArrayMap<PDG_WorkItemID, bool>;

/// Array, set and map of work items
using PDG_WorkItemArray         = UT_Array<PDG_WorkItem*>;
using PDG_WorkItemConstArray    = UT_Array<const PDG_WorkItem*>;
using PDG_WorkItemSet           = UT_ArraySet<PDG_WorkItem*>;
using PDG_WorkItemConstSet      = UT_ArraySet<const PDG_WorkItem*>;
using PDG_WorkItemMap           = UT_Map<PDG_WorkItem*, PDG_WorkItemSet>;
using PDG_WorkItemConstMap      = UT_Map<const PDG_WorkItem*, PDG_WorkItemSet>;
using PDG_WorkItemBoolMap       = UT_ArrayMap<PDG_WorkItem*, bool>;
using PDG_WorkItemConstBoolMap  = UT_ArrayMap<const PDG_WorkItem*, bool>;

/// Pair and array of work item pairs
using PDG_WorkItemPair          = std::pair<PDG_WorkItem*, PDG_WorkItem*>;
using PDG_WorkItemPairArray     = UT_Array<PDG_WorkItemPair>;

/// Array and set of batch work items
using PDG_BatchWorkItemArray    = UT_Array<PDG_BatchWorkItem*>;
using PDG_BatchWorkItemSet      = UT_ArraySet<PDG_BatchWorkItem*>;

/// Array, set and map of nodes
using PDG_NodePtr               = UT_UniquePtr<PDG_Node>;
using PDG_NodePtrMap            = UT_ArrayStringMap<PDG_NodePtr>;

using PDG_NodeArray             = UT_Array<PDG_Node*>;
using PDG_NodeSet               = UT_ArraySet<PDG_Node*>;
using PDG_NodeMap               = UT_ArrayStringMap<PDG_Node*>;

/// Array of input/output/parameter ports
using PDG_PortArray             = UT_Array<PDG_Port*>;

/// Set of schedulers
using PDG_SchedulerSet          = UT_Set<PDG_Scheduler*>;
using PDG_SchedulerArray        = UT_Array<PDG_Scheduler*>;

typedef UT_Optional<fpreal>     OptionalFrame;

/// Enumeration of supported platforms, for work item command line array
enum class PDG_Platform
{
    /// No specified platform
    eUndefined  = -1,

    /// The linux platform index
    eLinux      = 0,

    /// The mac platform index
    eMac        = 1,

    /// The windows platform index
    eWindows    = 2,
};

/// Enumeration of activiation modes for the batch, i.e. the condition under
/// which the batch item is first submitted to the scheduler
enum class PDG_BatchActivation
{
    /// The batch is scheduled once any of the subitems are ready to cook
    eAny,

    /// The batch is scheduled once the first sub item is ready to cook
    eFirst,

    /// The batch is scheduled once all of the subitems are ready to cook
    eAll,

    /// The batch is scheduled once a specific number of subitems are ready
    /// to cook
    eFixed
};

/// Enumeration of callback return types
enum class PDG_CallbackResult
{
    /// The callback failed to execute
    eFailure,

    /// The callback executed successfully
    eSuccess,

    /// The callback is missing or undefined
    eMissing,

    /// Special "None" case -- the callback took no action or returned no
    /// results
    eNone,

    /// Special "All" case -- the callback returned all results
    eAll,
};

/// Enumeration of service block cook modes
enum class PDG_ServiceBlockCookType
{
    /// Work items will never cook using the service associated with the 
    /// parent block
    eNever,

    /// Work items will cook the parent block's service if it matches the
    /// service name for the node
    eMatch,

    /// Work items will always use the parent block's service
    eAlways,
};

/// When service clients should be reset
enum class PDG_ServiceResetWhen
{
    /// The service client is not reset
    eNone           = 0x0,

    /// The service client is reset at the start of a work item or block cook
    eBeforeCook     = 0x1,

    /// The service client is reset at the end of a work item or block cook
    eAfterCook      = 0x2,

    /// The service is reset at the beginning and end of a cook
    eBoth           = 0x3
};

/// Service client reset operation, performed each time work items acquire a
/// new client.
enum class PDG_ServiceResetType
{
    /// The service client is not reset
    eNone,

    /// The service client is sent the "reset" command
    eReset,

    /// The service client process is restarted
    eRestart
};

/// Enumeration of the different types of service owner
enum class PDG_ServiceOwner
{
    /// The service is owned by a scheduler, which means it will be tied to
    /// the lifetime of the scheduler node(s).
    eScheduler,

    /// The service is owned by the session, which means it will be stopped
    /// only if stopped by the user or Houdini is closed.
    eSession
};

/// Enumeration of the different states that a service can be in
enum class PDG_ServiceState
{
    // The service is not running
    eStopped,

    // The service is in the process of stopping. The service will remain in
    // this state until the MQ Server and all of the service clients have
    // been issued a command to shutdown.
    eStopping,

    // The service is in the process of starting. The service will remain in
    // this state until all of the service clients have fully started up.
    eStarting,

    // The service is fully running and all clients are available.
    eRunning,

    // The service is in an unrecoverable error state
    eError
};

/// Enumeration of service log types
enum class PDG_ServiceLogType
{
    /// The service does not do any logging -- stdout is routed to
    /// /dev/null
    eNone,

    /// The service logs to stdout
    eStdout,

    /// The service logs to a file on disk
    eFile
};

/// Enumeration of possible result values from starting a service
enum class PDG_ServiceStartResult
{
    /// An error occured and the service was not started
    eError,

    /// The service was successfully started
    eSuccess,

    /// The service was already running
    eRunning,

    /// The service clients are connecting in the background
    eConnecting
};

/// Node state, used for UI/progress reporting.
enum class PDG_NodeState
{
    /// The node is uncooked, either because it wasn't on the cook path or
    /// because it chose to generate no items
    eUncooked,

    /// The node is actively cooking work items
    eCooking,

    /// The node is completely cooked
    eCooked,

    /// One or more work items failed during the cook
    eFailed,

    /// One or more work items were canceled during the cook
    eCanceled,

    /// The node is waiting on upstream nodes to make progress
    eWaiting,

    /// The node is partially cooked, and likely won't make any progress
    /// during the rest of the active cook
    eIncomplete
};

/// Enumeration of node types in a PDG graph
enum class PDG_NodeType
{
    /// Mapper nodes -- add dependencies between upstream and downstream
    /// work items [Deprecated]
    eMapper,

    /// Partitioner nodes -- group multiple upstream work items into
    /// partitions with a common property
    ePartitioner,

    /// Processor nodes -- generate zero more more new work items from
    /// upstream work items that perform real work
    eProcessor,

    /// Scheduler nodes -- submits work items to some sort of scheduling
    /// or farm system
    eScheduler,

    /// Placeholder/undefined node type
    eUndefined
};

/// Enumeration of node subtypes
enum class PDG_NodeSubtype
{
    /// A regular node -- default value
    eRegular,

    /// A feedback begin node -- part of a feedback block
    eFeedbackBegin,

    /// A feedback end node -- part of a feedback block
    eFeedbackEnd,

    /// A utility node, such as a null or switch
    eUtility,

    /// Placeholder/undefined node subtype
    eUndefined
};

/// Enumeration of node port display type, e.g. menus or toggles, for
/// parameters
enum class PDG_PortDisplayType
{
    /// Default display type
    eDefault    = 0x0,

    /// Dropdown menu display
    eMenu       = 0x01,

    /// Toggle display
    eToggle     = 0x02,

    /// Join-next display
    eJoin       = 0x04,

    /// Separator display
    eSeparator  = 0x08,

    /// No label display
    eNoLabel    = 0x10,

    /// Operator path display
    eOperator   = 0x20,
};

/// Enumeration of node port types
enum class PDG_PortType
{
    /// Input connection
    eInput,

    /// Output connection
    eOutput,

    /// Parameter
    eParameter,

    /// Port type guard/count
    eCount
};

/// Enumeration of evaluation states that a work item can be in. Used when
/// checking if the subitem is able to evaluate yet.
enum class PDG_WorkItemEvalState
{
    /// The work item is blocked on a dependency
    eEvalBlocked,

    /// The work item is ready to cook
    eEvalReady,

    /// The work item has a failed dependency
    eEvalFailed,
};

/// Enumeration of work item log message types
enum class PDG_WorkItemLogType
{
    /// Error log message
    eLogError,

    /// Warning log message
    eLogWarning,

    /// Plain log message
    eLogMessage,

    /// Raw log data
    eLogRaw,
};

/// Enumeration of sort order types, currently used by the partitionItems
/// method
enum class PDG_WorkItemSortOrder : uint8
{
    /// Explicitly chosen no sorting
    eSortNone,

    /// Index based sorting
    eSortIndex,

    /// Input ordering
    eSortInputOrder,

    /// Order by a specific attribute value
    eSortAttribute,

    /// Order by the work item's frame value
    eSortFrame,
};

/// Enum of possible work item states
enum class PDG_WorkItemState : uint8
{
    /// Undefined state, e.g. for uninitialized data. Work items should never
    /// actually have this state
    eUndefined,

    /// The item is uncooked and no cooked has been attempted yet
    eUncooked,  

    /// The item is uncooked and waiting on its dependencies to finish 
    /// cooking
    eWaiting,

    /// The item has been sent to the scheduler(s), but might not yet
    /// be executing
    eScheduled,

    /// The item is cooking
    eCooking,

    /// The item has finished cooking and succeeded
    eCookedSuccess,

    /// The item has was marked as successfully cooked because it a cached
    /// file was found on disk
    eCookedCache,

    /// The item has finished cooking and failed
    eCookedFail,

    /// The item has finished cooking by cancellation
    eCookedCancel,

    /// The item was dirty; it may have been cooked before, but not 
    /// necessarily. This is effectively the same as uncooked, but it
    /// gives an indication that item may need additional cleanup or 
    /// repartitioning.
    eDirty,

    /// The number of states
    eStateCount,
};

/// Enum of work item types
enum class PDG_WorkItemType : uint8
{
    /// A static or dynamic work item that does real work, and has one 
    /// upstream parent
    eRegular,

    /// A batch item, which consists of one or more subitems that are 
    /// Regular type items
    eBatch,

    /// A partition, which has a list of upstream components
    ePartition,
};

/// Enum of work item runtime types
enum class PDG_WorkItemExecutionType : uint8
{
    /// A regular work item, with normal running time
    eRegular,

    /// A long running work item that's process may outlive the cooking state
    /// of the work item
    eLongRunning,

    /// A work item that cleans up another long running item
    eCleanup
};

/// Enumeration of work item cook types
enum class PDG_WorkItemCookType :  uint8
{
    /// The work item does its processing during the generation stage,
    /// and doesn't "cook" in the traditional sense.
    eGenerate,

    /// The work item cooks in process
    eInProcess,

    /// The work item cooks out of process
    eOutOfProcess,

    /// The work item cooks as a service
    eService,

    /// Unspecified/automatic cook type
    eAutomatic
};

/// Enumeration of entities that can be registered with PDG_TypeRegistry
enum class PDG_RegistrationType
{
    /// Custom external dependency
    eDependency,

    /// Custom node definition
    eNode,

    /// Custom scheduler definition
    eScheduler,

    /// Custom work item data definition
    eWorkItem,

    /// Custom service defintion
    eService,

    eCount
};

/// Enumeration of merge strategies for handling collisions when
/// deserializing attributes into a map with existing attributes
enum class PDG_AttributeCollision
{
    /// The existing attribute is kept and the deserialized attribute is
    /// discarded
    eKeep,

    /// The existing attribute is replaced with the deserialized attribute
    eReplace,

    /// Deserialization fails when an existing attribute is found with the
    /// same name as the one being deserialized
    eError
};

enum PDG_CommandType
{
    PDG_COMMAND_CHUNK,
    PDG_USER_COMMAND,
    PDG_RUNTIME_COMMAND
};

/// Base type for types registered using PDG_TypeRegistry
using PDG_BaseType = PDGT_BaseType<PDG_RegistrationType>;

/// Specialization type which encapsulates the produced class and
/// construction args, for a type registered in the registry
template <typename Class,
          typename Pointer,
          PDG_RegistrationType type,
          typename... Args>
using PDG_RegisteredType = PDGT_RegisteredType<
    Class, Pointer, PDG_RegistrationType, type, Args...>;

/// Base class for a concrete instance of a type created by the
/// registry
using PDG_TypeInstance = PDGT_TypeInstance<PDG_RegistrationType>;

#endif /* __PDG_TYPES_H__ */