Disposable Pattern - Learning Module

Loading content...

0/246

Resource Cleanup Guarantee

The Cleanup Promise

Resource cleanup is not about best efforts—it's about guarantees. When you acquire a database connection, file handle, or distributed lock, you're making an implicit promise to the system: "I will return this resource when I'm done." Breaking this promise leads to system degradation, outages, and cascading failures.

But guaranteeing cleanup is harder than it sounds. Consider the challenges:

What if an exception occurs during cleanup itself?
What if multiple resources must be cleaned up, and one cleanup fails?
What if resources are shared across threads?
What if a resource depends on another resource that's already been disposed?
What if the process crashes before cleanup runs?

This page explores techniques for guaranteeing cleanup—from structured patterns that handle edge cases to defensive programming that maintains integrity even when things go wrong.

What You Will Learn

By the end of this page, you will master: (1) Cleanup ordering and dependency management, (2) Partial failure handling during multi-resource cleanup, (3) Thread-safe disposal patterns, (4) Defensive techniques for cleanup reliability, (5) System-level considerations for crash recovery.

The Cleanup Contract Deep Dive

When we speak of "guaranteeing cleanup," we must be precise about what we're guaranteeing. Absolute guarantees are impossible (hardware failures, power outages), but we can make strong guarantees under normal operating conditions.

Levels of Cleanup Guarantee:

Cleanup Guarantee Levels
Level	Guarantee	Technique	Failure Mode
Basic	Cleanup runs if no exceptions	Sequential cleanup calls	Any exception skips remaining cleanup
Exception-Safe	Cleanup runs even on exception	try-finally / using / with	Process crash skips cleanup
Failure-Tolerant	All resources cleaned even if some fail	Aggregate exceptions, continue cleanup	Process crash skips cleanup
Thread-Safe	Cleanup runs exactly once, even with concurrent access	Atomic flags, locks	Deadlock can prevent cleanup
Crash-Recoverable	Resources recovered after process restart	External cleanup, leases, TTL	System failure before recovery

Most applications need at least failure-tolerant cleanup. High-reliability systems require thread-safe patterns. Distributed systems often need crash-recoverable mechanisms.

The Dispose Method Contract (Formalized):

Dispose Contract Requirements

•Idempotence — Calling dispose() multiple times must be safe and have the same effect as calling it once.
•Non-Throwing — dispose() should not throw exceptions during normal operation. Cleanup errors should be logged, not propagated.
•Completeness — All resources must be released, even if releasing one resource fails.
•Ordering — Resources must be released in correct order (reverse of acquisition, dependency-aware).
•Finality — After dispose(), the object must be in a terminal state. No operations should succeed.
•Atomicity (for thread-safety) — The disposed flag transition must be atomic to prevent double-dispose races.

The No-Throw Principle

Throwing from dispose() is almost always wrong. Consider: if the try block throws ExceptionA, and finally/dispose throws ExceptionB, the caller typically only sees ExceptionB. The original error is lost. Worse, if cleanup of resource A throws, resource B may never be cleaned. Always catch and log cleanup errors.

Cleanup Ordering and Dependencies

When multiple resources are involved, cleanup order matters. The general rule is reverse order of acquisition: the last resource acquired is the first to be released. This mirrors stack semantics and respects resource dependencies.

Why Reverse Order?

Consider a transaction that depends on a connection:

Acquire connection
Begin transaction (depends on connection)
Use transaction
Commit/rollback transaction (must happen before connection closes)
Close connection

If you close the connection before the transaction, the transaction's commit/rollback will fail—or worse, leave the database in an inconsistent state.

Converting Mermaid diagram...

cleanup-ordering.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
/**
 * Cleanup Ordering Patterns
 * 
 * Resources acquired first are cleaned up last.
 * This respects dependency relationships.
 */
 
// Pattern 1: Nested try-finally (manual ordering)
function processWithConnection(): void {
    const connection = connectionPool.acquire();
    try {
        const transaction = connection.beginTransaction();
        try {
            const statement = transaction.createStatement();
            try {
                const resultSet = statement.executeQuery("SELECT * FROM users");
                try {
                    // Process results
                    processResults(resultSet);
                } finally {
                    resultSet.close();      // 1st: inner-most
                }
            } finally {
                statement.close();          // 2nd
            }
            transaction.commit();
        } catch (e) {
            transaction.rollback();
            throw e;
        } finally {
            // Transaction is implicitly closed after commit/rollback
        }
    } finally {
        connection.close();                 // Last: outer-most
    }
}
 
// Pattern 2: Resource Stack (cleaner)
class ResourceStack implements Disposable {
    private resources: Disposable[] = [];
    private _isDisposed = false;
    
    get isDisposed(): boolean {
        return this._isDisposed;
    }
    
    /**
     * Register a resource for cleanup.
     * Resources are disposed in reverse order of registration.
     */
    push<T extends Disposable>(resource: T): T {
        if (this._isDisposed) {
            // If stack is already disposed, dispose immediately
            resource.dispose();
            throw new Error("Cannot push to disposed ResourceStack");
        }
        this.resources.push(resource);
        return resource;
    }
    
    /**
     * Dispose all resources in reverse order.
     * Continues cleanup even if individual resources fail.
     */
    dispose(): void {
        if (this._isDisposed) return;
        this._isDisposed = true;
        
        const errors: Error[] = [];
        
        // Reverse order disposal
        while (this.resources.length > 0) {
            const resource = this.resources.pop()!;
            try {
                resource.dispose();
            } catch (error) {
                errors.push(error as Error);
                console.error("Resource cleanup error:", error);
            }
        }
        
        // Optionally aggregate errors for reporting
        if (errors.length > 0) {
            console.error(`Cleanup completed with ${errors.length} error(s)`);
        }
    }
}
 
// Usage: Clean, flat code with guaranteed ordering
function processWithResourceStack(): void {
    const stack = new ResourceStack();
    try {
        const connection = stack.push(connectionPool.acquire());
        const transaction = stack.push(connection.beginTransaction());
        const statement = stack.push(transaction.createStatement());
        const resultSet = stack.push(statement.executeQuery("SELECT * FROM users"));
        
        processResults(resultSet);
        transaction.commit();
    } catch (e) {
        // Transaction rollback handled by dispose
        throw e;
    } finally {
        stack.dispose();  // All resources cleaned in reverse order
    }
}
 
// Pattern 3: Dependency-Aware Cleanup
interface DisposableWithDependencies extends Disposable {
    readonly dependencies: DisposableWithDependencies[];
}
 
function disposeWithDependencies(root: DisposableWithDependencies): void {
    // Topological sort to find correct disposal order
    const disposed = new Set<DisposableWithDependencies>();
    
    function disposeRecursive(node: DisposableWithDependencies): void {
        if (disposed.has(node)) return;
        
        // Dispose dependencies first (reverse of "depends on")
        for (const dep of node.dependencies) {
            disposeRecursive(dep);
        }
        
        // Then dispose this node
        try {
            node.dispose();
        } catch (e) {
            console.error("Dispose error:", e);
        }
        disposed.add(node);
    }
    
    // Note: For "A depends on B", B should be disposed AFTER A
    // This is the inverse - call it on leaf nodes first
    disposeRecursive(root);
}

The Resource Stack Pattern

The ResourceStack pattern (similar to Python's ExitStack, Go's defer stack) provides a clean way to manage multiple resources with automatic reverse-order disposal. Acquire resources with push(), then dispose the stack once. This eliminates deeply nested try-finally blocks.

Handling Partial Cleanup Failures

What happens when you have five resources to clean up, and the cleanup of the third one fails? A naive approach might abort, leaving resources four and five leaked. A guaranteed cleanup approach must continue.

The Complete Cleanup Principle:

When disposing multiple resources, dispose ALL of them, regardless of individual failures. Collect errors for later analysis, but don't let one failure prevent subsequent cleanup.

partial-failure-handling.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
/**
 * Partial Failure Handling in Multi-Resource Cleanup
 * 
 * The key principle: NEVER let one cleanup failure prevent others.
 */
 
// ❌ WRONG: First failure aborts remaining cleanup
function wrongMultiCleanup(resources: Disposable[]): void {
    for (const resource of resources) {
        resource.dispose();  // If this throws, remaining resources leak!
    }
}
 
// ✅ CORRECT: All resources cleaned, errors aggregated
function safeMultiCleanup(resources: Disposable[]): CleanupResult {
    const errors: CleanupError[] = [];
    let disposedCount = 0;
    
    for (const resource of resources) {
        try {
            resource.dispose();
            disposedCount++;
        } catch (error) {
            errors.push({
                resource: resource.constructor.name,
                error: error as Error,
            });
            // Continue to next resource!
        }
    }
    
    return {
        success: errors.length === 0,
        disposedCount,
        totalCount: resources.length,
        errors,
    };
}
 
interface CleanupError {
    resource: string;
    error: Error;
}
 
interface CleanupResult {
    success: boolean;
    disposedCount: number;
    totalCount: number;
    errors: CleanupError[];
}
 
/**
 * A composite disposable that guarantees complete cleanup
 */
class CompositeDisposable implements Disposable {
    private resources: Disposable[] = [];
    private _isDisposed = false;
    private _cleanupResult: CleanupResult | null = null;
    
    get isDisposed(): boolean {
        return this._isDisposed;
    }
    
    get cleanupResult(): CleanupResult | null {
        return this._cleanupResult;
    }
    
    add(resource: Disposable): void {
        if (this._isDisposed) {
            // Immediately dispose if container is already disposed
            try {
                resource.dispose();
            } catch (e) {
                console.error("Immediate dispose failed:", e);
            }
            return;
        }
        this.resources.push(resource);
    }
    
    /**
     * Disposes all resources, guaranteeing complete cleanup.
     * 
     * Post-conditions:
     * - All resources have had dispose() called
     * - cleanupResult contains success/failure information
     * - This composite is in disposed state
     */
    dispose(): void {
        if (this._isDisposed) return;
        this._isDisposed = true;
        
        const errors: CleanupError[] = [];
        
        // Reverse order disposal
        for (let i = this.resources.length - 1; i >= 0; i--) {
            const resource = this.resources[i];
            try {
                resource.dispose();
            } catch (error) {
                errors.push({
                    resource: `${resource.constructor.name}[${i}]`,
                    error: error as Error,
                });
            }
        }
        
        this._cleanupResult = {
            success: errors.length === 0,
            disposedCount: this.resources.length - errors.length,
            totalCount: this.resources.length,
            errors,
        };
        
        // Clear references to allow GC
        this.resources = [];
        
        // Log but don't throw
        if (errors.length > 0) {
            console.error(
                `CompositeDisposable: ${errors.length} cleanup error(s)`,
                errors
            );
        }
    }
}
 
/**
 * Extension: Disposable with cleanup verification
 */
interface VerifiableDisposable extends Disposable {
    verifyCleanup(): VerificationResult;
}
 
interface VerificationResult {
    isCleanedUp: boolean;
    details: string;
}
 
class VerifiedFileHandle implements VerifiableDisposable {
    private handle: NativeFileHandle | null;
    private filePath: string;
    private _isDisposed = false;
    
    constructor(path: string) {
        this.filePath = path;
        this.handle = NativeFS.open(path);
    }
    
    get isDisposed(): boolean {
        return this._isDisposed;
    }
    
    dispose(): void {
        if (this._isDisposed) return;
        this._isDisposed = true;
        
        if (this.handle !== null) {
            try {
                NativeFS.close(this.handle);
            } catch (e) {
                console.error(`Failed to close ${this.filePath}:`, e);
            }
            this.handle = null;
        }
    }
    
    /**
     * Verify that cleanup was effective.
     * Useful for debugging and testing.
     */
    verifyCleanup(): VerificationResult {
        if (!this._isDisposed) {
            return {
                isCleanedUp: false,
                details: `${this.filePath}: dispose() not called`,
            };
        }
        
        if (this.handle !== null) {
            return {
                isCleanedUp: false,
                details: `${this.filePath}: handle still held after dispose()`,
            };
        }
        
        // Additional verification: check if file is actually released
        const isFileLocked = NativeFS.isFileLocked(this.filePath);
        if (isFileLocked) {
            return {
                isCleanedUp: false,
                details: `${this.filePath}: file still locked by process`,
            };
        }
        
        return {
            isCleanedUp: true,
            details: `${this.filePath}: fully released`,
        };
    }
}

Error Aggregation vs. Suppression

Java's try-with-resources suppresses close() exceptions and attaches them to the primary exception (getSuppressed()). TypeScript/JavaScript can use AggregateError or similar patterns. The key is preserving error information for debugging while still completing all cleanup operations.

Thread-Safe Disposal Patterns

In concurrent environments, disposal introduces race conditions:

Double-dispose: Two threads call dispose() simultaneously
Use-after-dispose: Thread A uses the resource while Thread B disposes it
Dispose-during-use: Thread A is in the middle of an operation when Thread B disposes

Thread-safe disposal requires careful synchronization.

thread-safe-disposal.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
/**
 * Thread-Safe Disposal Patterns
 * 
 * Note: JavaScript is single-threaded, but these patterns apply
 * to async code and are directly applicable in languages like
 * Java, C#, Go, and Rust.
 */
 
// Pattern 1: Atomic Flag with Compare-And-Swap
class ThreadSafeDisposable implements Disposable {
    // In real multi-threaded code, this would use AtomicBoolean
    // or equivalent synchronization primitive
    private _isDisposed = false;
    private _disposeLock = new AsyncLock();
    
    get isDisposed(): boolean {
        return this._isDisposed;
    }
    
    async dispose(): Promise<void> {
        // Only one thread can enter this block
        await this._disposeLock.acquire();
        try {
            if (this._isDisposed) {
                return;  // Already disposed by another thread
            }
            this._isDisposed = true;
            
            // Perform actual cleanup
            await this.releaseResources();
        } finally {
            this._disposeLock.release();
        }
    }
    
    protected async releaseResources(): Promise<void> {
        // Actual cleanup logic
    }
}
 
// Pattern 2: Reference Counting
class RefCountedResource implements Disposable {
    private refCount = 1;  // Start with one reference
    private _isDisposed = false;
    private resource: NativeResource;
    private lock = new AsyncLock();
    
    get isDisposed(): boolean {
        return this._isDisposed;
    }
    
    /**
     * Acquire an additional reference.
     * Caller must call release() when done.
     */
    async acquire(): Promise<RefCountedResource> {
        await this.lock.acquire();
        try {
            if (this._isDisposed) {
                throw new Error("Cannot acquire reference to disposed resource");
            }
            this.refCount++;
            return this;
        } finally {
            this.lock.release();
        }
    }
    
    /**
     * Release a reference.
     * Resource is only truly disposed when all references are released.
     */
    async release(): Promise<void> {
        await this.lock.acquire();
        try {
            this.refCount--;
            
            if (this.refCount === 0 && !this._isDisposed) {
                this._isDisposed = true;
                await this.doDispose();
            }
        } finally {
            this.lock.release();
        }
    }
    
    /**
     * Implements Disposable.dispose() - releases original reference.
     */
    async dispose(): Promise<void> {
        await this.release();
    }
    
    private async doDispose(): Promise<void> {
        this.resource.close();
    }
}
 
// Pattern 3: Guarded Operations
class GuardedDisposable implements Disposable {
    private _isDisposed = false;
    private activeOperations = 0;
    private lock = new AsyncLock();
    private disposeWaiters: Array<() => void> = [];
    
    get isDisposed(): boolean {
        return this._isDisposed;
    }
    
    /**
     * Execute an operation with disposal protection.
     * Returns null if resource is already disposed.
     */
    async withGuard<T>(operation: () => Promise<T>): Promise<T | null> {
        await this.lock.acquire();
        try {
            if (this._isDisposed) {
                return null;
            }
            this.activeOperations++;
        } finally {
            this.lock.release();
        }
        
        try {
            return await operation();
        } finally {
            await this.lock.acquire();
            try {
                this.activeOperations--;
                if (this.activeOperations === 0 && this.disposeWaiters.length > 0) {
                    // Notify waiters that all operations are complete
                    for (const waiter of this.disposeWaiters) {
                        waiter();
                    }
                    this.disposeWaiters = [];
                }
            } finally {
                this.lock.release();
            }
        }
    }
    
    /**
     * Dispose after all active operations complete.
     */
    async dispose(): Promise<void> {
        await this.lock.acquire();
        
        if (this._isDisposed) {
            this.lock.release();
            return;
        }
        
        this._isDisposed = true;  // Prevent new operations
        
        if (this.activeOperations > 0) {
            // Wait for active operations to complete
            await new Promise<void>((resolve) => {
                this.disposeWaiters.push(resolve);
                this.lock.release();
            });
        } else {
            this.lock.release();
        }
        
        // Now safe to dispose
        await this.doActualDispose();
    }
    
    private async doActualDispose(): Promise<void> {
        // Actual cleanup
    }
}
 
// Utility: Simple async lock for demonstrations
class AsyncLock {
    private locked = false;
    private waiting: Array<() => void> = [];
    
    async acquire(): Promise<void> {
        while (this.locked) {
            await new Promise<void>((resolve) => {
                this.waiting.push(resolve);
            });
        }
        this.locked = true;
    }
    
    release(): void {
        this.locked = false;
        const next = this.waiting.shift();
        if (next) next();
    }
}

Disposal and Deadlocks

Be careful with locks in dispose(). If dispose() acquires lock A while holding resources that need lock A to release, you have a deadlock. Design cleanup to be lock-free where possible, or use hierarchical locking with strict ordering.

Crash Recovery and External Cleanup

What happens when the process crashes before dispose() runs? The finally block never executes. The resource leaks. For critical resources, this is unacceptable.

Strategies for Crash-Resilient Cleanup:

Crash Recovery Techniques

•External Cleanup Process — A separate watchdog process monitors resource usage and cleans up after crashed processes.
•Resource Leases with TTL — Resources expire automatically if not renewed. If a process dies, its resources auto-release after the TTL.
•Heartbeat-Based Cleanup — Processes send heartbeats. When heartbeats stop, their resources are reclaimed.
•Write-Ahead Logging — Before acquiring resources, log the intent. On startup, replay the log and clean up orphaned resources.
•Transactional Resource Management — Use database transactions to track resource state. Uncommitted resources are rolled back.

crash-recovery.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
/**
 * Crash Recovery Patterns
 * 
 * These patterns ensure cleanup even if the process dies.
 */
 
// Pattern 1: Leased Resource with Automatic Expiry
interface LeasedResource {
    resourceId: string;
    leaseExpiry: Date;
}
 
class ResourceLeaseManager {
    private leases = new Map<string, LeasedResource>();
    private cleanupInterval: NodeJS.Timeout;
    
    constructor(private leaseDurationMs: number = 30000) {
        // Background cleanup of expired leases
        this.cleanupInterval = setInterval(
            () => this.cleanupExpired(),
            this.leaseDurationMs / 2
        );
    }
    
    /**
     * Acquire a resource with an automatic expiry lease.
     * If the process dies, the lease expires and the resource is reclaimed.
     */
    acquire(resourceId: string): LeaseToken {
        const expiry = new Date(Date.now() + this.leaseDurationMs);
        
        this.leases.set(resourceId, {
            resourceId,
            leaseExpiry: expiry,
        });
        
        return new LeaseToken(resourceId, this);
    }
    
    /**
     * Renew a lease to prevent expiry.
     * Long-running processes should renew periodically.
     */
    renew(resourceId: string): void {
        const lease = this.leases.get(resourceId);
        if (lease) {
            lease.leaseExpiry = new Date(Date.now() + this.leaseDurationMs);
        }
    }
    
    /**
     * Explicitly release a resource (normal dispose path).
     */
    release(resourceId: string): void {
        const lease = this.leases.get(resourceId);
        if (lease) {
            this.doCleanup(resourceId);
            this.leases.delete(resourceId);
        }
    }
    
    /**
     * Background job: clean up expired leases.
     * This handles the case where a process died without releasing.
     */
    private cleanupExpired(): void {
        const now = new Date();
        
        for (const [resourceId, lease] of this.leases) {
            if (lease.leaseExpiry < now) {
                console.log(`[LeaseManager] Expired lease: ${resourceId}`);
                this.doCleanup(resourceId);
                this.leases.delete(resourceId);
            }
        }
    }
    
    private doCleanup(resourceId: string): void {
        // Actual cleanup logic (close connection, release lock, etc.)
        NativeResourceManager.release(resourceId);
    }
}
 
class LeaseToken implements Disposable {
    private _isDisposed = false;
    private renewalInterval: NodeJS.Timeout | null = null;
    
    constructor(
        private resourceId: string,
        private manager: ResourceLeaseManager
    ) {
        // Auto-renew lease while token is alive
        this.renewalInterval = setInterval(
            () => this.manager.renew(this.resourceId),
            10000  // Renew every 10 seconds
        );
    }
    
    get isDisposed(): boolean {
        return this._isDisposed;
    }
    
    dispose(): void {
        if (this._isDisposed) return;
        this._isDisposed = true;
        
        // Stop renewal
        if (this.renewalInterval) {
            clearInterval(this.renewalInterval);
            this.renewalInterval = null;
        }
        
        // Release the lease
        this.manager.release(this.resourceId);
    }
}
 
// Pattern 2: Write-Ahead Log for Crash Recovery
interface ResourceLogEntry {
    operation: 'ACQUIRE' | 'RELEASE';
    resourceId: string;
    timestamp: Date;
    processId: string;
}
 
class WALResourceManager {
    private wal: WriteAheadLog<ResourceLogEntry>;
    private processId: string;
    
    constructor() {
        this.processId = generateProcessId();
        this.wal = new WriteAheadLog('resources.wal');
        
        // On startup, recover from WAL
        this.recoverFromWAL();
    }
    
    async acquire(resourceId: string): Promise<void> {
        // Log intent BEFORE acquiring
        await this.wal.append({
            operation: 'ACQUIRE',
            resourceId,
            timestamp: new Date(),
            processId: this.processId,
        });
        
        // Now acquire
        await NativeResourceManager.acquire(resourceId);
    }
    
    async release(resourceId: string): Promise<void> {
        // Release first
        await NativeResourceManager.release(resourceId);
        
        // Then log
        await this.wal.append({
            operation: 'RELEASE',
            resourceId,
            timestamp: new Date(),
            processId: this.processId,
        });
    }
    
    private async recoverFromWAL(): Promise<void> {
        const entries = await this.wal.readAll();
        
        // Find resources that were acquired but not released
        const unreleased = new Set<string>();
        
        for (const entry of entries) {
            if (entry.operation === 'ACQUIRE') {
                unreleased.add(entry.resourceId);
            } else if (entry.operation === 'RELEASE') {
                unreleased.delete(entry.resourceId);
            }
        }
        
        // Clean up orphaned resources
        for (const resourceId of unreleased) {
            console.log(`[WAL Recovery] Cleaning up orphaned: ${resourceId}`);
            try {
                await NativeResourceManager.release(resourceId);
            } catch (e) {
                console.error(`[WAL Recovery] Failed to clean ${resourceId}:`, e);
            }
        }
        
        // Compact the WAL
        await this.wal.compact();
    }
}

Distributed Systems and Leases

In distributed systems, lease-based resource management is the standard pattern. Zookeeper ephemeral nodes, Redis key TTLs, and database connection pool timeouts all implement variants of this pattern. The lease duration represents a trade-off: short leases recover quickly but require more renewal overhead; long leases are efficient but slow to recover.

Defensive Cleanup Techniques

Beyond the core patterns, several defensive techniques increase cleanup reliability:

Defensive Techniques

•Null Checks Before Cleanup — Always check if a resource is null before calling cleanup methods. The resource may not have been successfully acquired.
•Multiple Null Assignment — Set resource references to null after cleanup. This prevents accidental reuse and helps GC.
•Cleanup Verification — After cleanup, verify the resource is actually released (files unlocked, connections closed, etc.).
•Timeout-Bounded Cleanup — Set timeouts on cleanup operations. A stuck cleanup shouldn't hang the entire application.
•Cleanup Logging — Log cleanup operations, especially failures. This aids debugging resource leaks.
•Cleanup Metrics — Track cleanup success rates, timing, and failures. Monitor for degradation.

defensive-cleanup.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
/**
 * Defensive Cleanup Implementation
 */
 
class DefensiveDisposable implements Disposable {
    private resource: NativeResource | null = null;
    private _isDisposed = false;
    private acquisitionTime: Date | null = null;
    private disposalTime: Date | null = null;
    
    get isDisposed(): boolean {
        return this._isDisposed;
    }
    
    async acquire(): Promise<void> {
        if (this._isDisposed) {
            throw new Error("Cannot acquire on disposed object");
        }
        
        this.acquisitionTime = new Date();
        console.log(`[Resource] Acquiring at ${this.acquisitionTime.toISOString()}`);
        
        try {
            this.resource = await NativeResource.create();
        } catch (e) {
            console.error("[Resource] Acquisition failed:", e);
            throw e;
        }
    }
    
    dispose(): void {
        // Idempotency check
        if (this._isDisposed) {
            console.log("[Resource] Already disposed, skipping");
            return;
        }
        
        this._isDisposed = true;
        this.disposalTime = new Date();
        
        // Log lifecycle
        const heldDuration = this.acquisitionTime 
            ? this.disposalTime.getTime() - this.acquisitionTime.getTime()
            : 0;
        console.log(`[Resource] Disposing after ${heldDuration}ms`);
        
        // Null check - resource might not have been acquired
        if (this.resource === null) {
            console.log("[Resource] No resource to dispose");
            return;
        }
        
        // Attempt cleanup with defensive error handling
        try {
            // Timeout-bounded cleanup
            const cleanup = Promise.race([
                this.resource.close(),
                this.timeout(5000).then(() => {
                    throw new Error("Cleanup timed out after 5 seconds");
                }),
            ]);
            
            // Note: In sync dispose, we can't await. In async dispose, we would.
            cleanup.catch(e => {
                console.error("[Resource] Cleanup error:", e);
            });
            
        } catch (error) {
            console.error("[Resource] Cleanup threw synchronously:", error);
        } finally {
            // Clear reference regardless of success/failure
            this.resource = null;
        }
        
        // Verification (best effort)
        this.verifyCleanup();
    }
    
    private timeout(ms: number): Promise<void> {
        return new Promise(resolve => setTimeout(resolve, ms));
    }
    
    private verifyCleanup(): void {
        // Implementation-specific verification
        // For example, check if file handles are released, connections closed, etc.
        if (this.resource !== null) {
            console.error("[Resource] Verification failed: reference not null");
        }
    }
}
 
/**
 * Cleanup metrics for monitoring
 */
class CleanupMetrics {
    private successCount = 0;
    private failureCount = 0;
    private totalCleanupTimeMs = 0;
    private maxCleanupTimeMs = 0;
    
    recordSuccess(durationMs: number): void {
        this.successCount++;
        this.totalCleanupTimeMs += durationMs;
        this.maxCleanupTimeMs = Math.max(this.maxCleanupTimeMs, durationMs);
    }
    
    recordFailure(error: Error): void {
        this.failureCount++;
        console.error("[CleanupMetrics] Recorded failure:", error);
    }
    
    getStats() {
        return {
            successCount: this.successCount,
            failureCount: this.failureCount,
            successRate: this.successCount / (this.successCount + this.failureCount),
            avgCleanupTimeMs: this.totalCleanupTimeMs / this.successCount,
            maxCleanupTimeMs: this.maxCleanupTimeMs,
        };
    }
}
 
const cleanupMetrics = new CleanupMetrics();
 
// Usage: Wrap dispose with metrics
function disposeWithMetrics(disposable: Disposable): void {
    const startTime = Date.now();
    try {
        disposable.dispose();
        cleanupMetrics.recordSuccess(Date.now() - startTime);
    } catch (error) {
        cleanupMetrics.recordFailure(error as Error);
    }
}

Summary: Resource Cleanup Guarantee

Key Takeaways

•Define Your Guarantee Level — Understand whether you need basic, exception-safe, failure-tolerant, thread-safe, or crash-recoverable cleanup.
•Respect Cleanup Order — Dispose resources in reverse order of acquisition. Use resource stacks for clean code.
•Handle Partial Failures — When disposing multiple resources, continue even if some fail. Aggregate errors for reporting.
•Design for Concurrency — Use atomic flags, locks, or reference counting to ensure thread-safe disposal.
•Plan for Crashes — For critical resources, use leases, TTLs, or write-ahead logging for crash recovery.
•Be Defensive — Null-check, log, verify, timeout, and monitor cleanup operations.

What's Next:

The final page of this module covers nested Disposables—the challenge of managing composite objects where one Disposable contains others. We'll explore ownership hierarchies, disposal cascades, and factory patterns for complex resource graphs.

Page Complete

You now understand how to guarantee resource cleanup under various failure modes. These patterns—from exception safety to crash recovery—ensure your applications maintain resource integrity even when things go wrong.