Stateful v Stateless Routines
Xperiflow Routines can be designed as either Stateful or Stateless, depending on whether they need to maintain data between Method Runs. This fundamental distinction affects how Routines behave, how they store information, and how they're used in workflows.
Info: The choice between stateful and stateless design is similar to choosing between a class with instance variables (stateful) versus static utility functions (stateless) in traditional programming.
Overview
Routines in Xperiflow fall into two categories based on whether they maintain state:
- Stateful Routines: Maintain internal data that persists across multiple executions. Each Routine Instance has its own state that can be updated and accessed by different method calls.
- Stateless Routines: Do not maintain any persistent state. Each execution is completely independent, with no memory of previous executions.
The distinction is determined by whether the Routine defines a custom initialization (constructor) function. If it does, the Routine is stateful; if it doesn't, the Routine is stateless.
Core Concepts
What Makes a Routine Stateful?
A Routine is considered stateful if it defines a custom __init__ function. This initialization function:
- Sets up the Routine Instance with initial configuration
- Establishes member variables that will persist across executions
- Prepares the Routine for use by its methods
When a stateful Routine is created, the __init__ function runs once, and the state it establishes persists for the lifetime of that Routine Instance.
What Makes a Routine Stateless?
A Routine is considered stateless if it does not define a custom __init__ function. Stateless Routines:
- Have no initialization logic
- Have no persistent member variables
- Treat each method execution as completely independent
Stateless Routines are similar to static methods—they perform operations based solely on their input parameters without relying on any stored state.
Stateful Routines
Characteristics
Stateful Routines maintain member variables—data that persists across all executions of methods on the same Routine Instance.
Key Features:
- Persistent State: Data stored in member variables survives between method executions
- Instance-Specific: Each Routine Instance has its own independent state
- Updatable: Member variables can be modified by method executions
- Shared Across Methods: All methods on the same instance share access to the same state
Member Variables
Member variables are the mechanism by which stateful Routines maintain state.
**Note:** The member variables are managed by the developer who wrote the Routine (Routine Developer).
What They Are:
- Named storage locations that hold data for a Routine Instance
- Defined as part of the Routine's structure
- Persist across all runs of methods on that instance
- Can be read-only or read-write
How They Work:
- Member variables are stored in a shared directory for the Routine Instance
- They're loaded lazily (only when accessed)
- They're saved automatically when modified
- They persist even if the Routine Instance isn't actively running
State Persistence
Stateful Routines persist their state between executions:
Persistence Mechanism:
- Member variables are serialized (pickled) and stored in the filesystem
- State survives system restarts, routine updates, and long periods of inactivity
- State is instance-specific—each Routine Instance has its own state
State Lifecycle:
- Initialization: When a Routine Instance is created, the
__init__method sets initial state - Execution: Methods can read and modify member variables
- Persistence: Modified member variables are automatically saved
- Retrieval: On subsequent executions, member variables are loaded from storage
Use Cases for Stateful Routines
Stateful Routines are ideal when you need:
- Accumulated Data: Routines that build up data over time (e.g., maintaining a conversation history, tracking statistics)
- Configuration Persistence: Routines that need to remember configuration set during initialization
- Cached Results: Routines that cache expensive computations for reuse
- Session Management: Routines that maintain session-like state across multiple interactions
- Progressive Processing: Routines that process data incrementally, building on previous results
Example Scenarios:
- Linear Regression: Maintains configuration settings (outlier removal preferences, fold count, imputation type) and trained models across multiple fit and predict operations. The configuration is set once during initialization and reused for all subsequent method calls.
- Operational Data Chat: Maintains database connections, table schemas, processed statistics, and conversation history. The routine processes data during initialization to create an embedding store, which is then reused for all natural language queries.
- K-means Clustering: Maintains normalization settings and deterministic model flags that are configured during initialization and applied consistently across fit and predict operations.
Stateless Routines
Characteristics
Stateless Routines have no persistent state and treat each execution as completely independent.
Key Features:
- No Persistent State: No data survives between executions
- Independent Executions: Each method call is self-contained
- Parameter-Driven: Behavior depends entirely on input parameters
- Predictable: Same inputs always produce the same outputs (assuming no external dependencies)
How Stateless Routines Work
Stateless Routines operate like pure functions:
Execution Model:
- Each method execution receives input parameters
- The method performs its work using only those parameters
- Results are returned, but no state is retained
- The next execution starts fresh with no memory of previous executions
No Member Variables:
- Stateless Routines cannot have member variables
- All data must be passed as parameters to methods
- No shared storage between executions
Use Cases for Stateless Routines
Stateless Routines are ideal when you need:
- Pure Transformations: Operations that transform input to output without side effects
- One-Time Operations: Tasks that don't need to remember previous executions
- Reproducible Results: Operations where the same inputs should always produce the same outputs
- Simple Utilities: Helper functions that perform discrete operations
- Parallel Execution: Operations that can run independently without coordination
Example Scenarios:
-
Frequency Resampler (Resample): Changes the periodicity of time series data (e.g., daily to weekly, monthly to daily). Each execution is independent—you provide the source data, source frequency, target frequency, and aggregation rules, and it returns the resampled data without maintaining any state between executions.
-
Source Data Analysis: Generates an HTML report with statistics and visualizations for any tabular dataset. Each execution analyzes the provided dataset independently and produces a report without storing any intermediate results or maintaining analysis history.
Comparing Stateful and Stateless Routines
Execution Behavior
Stateful Routines:
- First execution: Initializes state via
__init__, then executes method - Subsequent executions: Loads existing state, executes method (may modify state), saves state
- State accumulates or changes over time
Stateless Routines:
- Every execution: Receives parameters, performs work, returns results
- No state to load or save
- Each execution is identical in behavior (given same inputs)
Storage Requirements
Stateful Routines:
- Require storage space for member variables
- Storage grows as state accumulates
- State persists indefinitely (until instance is deleted)
Stateless Routines:
- No persistent storage required
- Only temporary storage during execution
- No storage between executions
Performance Considerations
Stateful Routines:
- Initial execution may be slower (initialization overhead)
- Subsequent executions may be faster (can use cached state)
- State loading adds overhead to each execution
- State saving adds overhead when variables are modified
Stateless Routines:
- Consistent execution time (no state management overhead)
- No loading or saving overhead
- May repeat work that could be cached in a stateful routine
Complexity
Stateful Routines:
- More complex to design (must manage state lifecycle)
- Must consider state initialization, updates, and persistence
- Need to handle state consistency and error recovery
- More powerful but require more careful design
Stateless Routines:
- Simpler to design (no state management)
- Easier to reason about (no hidden state)
- Less powerful but more predictable
- Easier to test and debug