Disposable Pattern

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

/**
 * The Disposable Interface - A Universal Contract
 * 
 * This interface establishes a contract between resource-holding objects
 * and the code that uses them. Any object implementing this interface
 * promises to release its resources when dispose() is called.
 */
interface Disposable {
    /**
     * Releases all resources held by this object.
     * 
     * After calling dispose():
     * - All external resources (files, connections, etc.) are released
     * - The object should not be used further (behavior undefined)
     * - Calling dispose() again should be safe (idempotent)
     * - This method should not throw exceptions during normal cleanup
     * 
     * @remarks
     * This is a deterministic cleanup method. Unlike finalizers, 
     * dispose() is called by the application at a predictable time,
     * allowing immediate resource release.
     */
    dispose(): void;
 
    /**
     * Indicates whether this object has been disposed.
     * Useful for guard checks in methods that require active resources.
     */
    readonly isDisposed: boolean;
}
 
/**
 * Example: A database connection implementing Disposable
 */
class DatabaseConnection implements Disposable {
    private connection: NativeConnection | null;
    private _isDisposed: boolean = false;
 
    constructor(connectionString: string) {
        // Acquire the expensive resource during construction
        this.connection = NativeConnectionFactory.create(connectionString);
        console.log(`[DatabaseConnection] Opened connection to ${connectionString}`);
    }
 
    get isDisposed(): boolean {
        return this._isDisposed;
    }
 
    /**
     * Execute a query on this connection.
     * Throws if the connection has been disposed.
     */
    executeQuery(sql: string): ResultSet {
        // Guard clause: Fail fast if already disposed
        if (this._isDisposed) {
            throw new ObjectDisposedException(
                "Cannot execute query on a disposed connection"
            );
        }
 
        return this.connection!.execute(sql);
    }
 
    /**
     * Implements Disposable.dispose()
     * 
     * Releases the database connection back to the connection pool.
     * This method is idempotent - calling it multiple times is safe.
     */
    dispose(): void {
        // Idempotent: Only dispose once
        if (this._isDisposed) {
            return;
        }
 
        // Mark as disposed FIRST (prevents race conditions)
        this._isDisposed = true;
 
        // Release the actual resource
        if (this.connection !== null) {
            try {
                this.connection.close();
                console.log("[DatabaseConnection] Connection closed and returned to pool");
            } catch (error) {
                // Log but don't throw - cleanup should be resilient
                console.error("[DatabaseConnection] Error during cleanup:", error);
            } finally {
                this.connection = null;
            }
        }
    }
}
 
/**
 * Custom exception for operations on disposed objects
 */
class ObjectDisposedException extends Error {
    constructor(message: string) {
        super(message);
        this.name = "ObjectDisposedException";
    }
}

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

/**
 * The Full Disposable Pattern
 * 
 * This implementation shows the complete, production-grade pattern with:
 * - Separation of managed and unmanaged resource cleanup
 * - Support for inheritance (subclasses can override cleanup)
 * - Idempotent disposal
 * - Thread-safety considerations
 */
 
interface Disposable {
    dispose(): void;
    readonly isDisposed: boolean;
}
 
/**
 * Base class demonstrating the full Dispose pattern.
 * Extend this to create disposable classes with proper cleanup semantics.
 */
abstract class DisposableBase implements Disposable {
    private _isDisposed: boolean = false;
    
    get isDisposed(): boolean {
        return this._isDisposed;
    }
    
    /**
     * Public dispose method - implements the Disposable interface.
     * 
     * This is what consumers call. It delegates to the protected
     * dispose(boolean) method and handles finalization suppression.
     */
    public dispose(): void {
        // Dispose managed and unmanaged resources
        this.disposeCore(true);
        
        // In languages with finalizers (C#, Java), we would suppress
        // finalization here since cleanup is already done:
        // GC.SuppressFinalize(this);
    }
    
    /**
     * Protected dispose method - contains the actual cleanup logic.
     * 
     * @param disposing If true, called from dispose() - clean up everything.
     *                  If false, called from finalizer - only clean unmanaged resources.
     * 
     * Subclasses override this to add their own cleanup, calling super.disposeCore(disposing).
     */
    protected disposeCore(disposing: boolean): void {
        if (this._isDisposed) {
            return;  // Idempotent - already disposed
        }
        
        if (disposing) {
            // Called from dispose(): Clean up managed resources
            // (objects that themselves implement Disposable)
            this.disposeManagedResources();
        }
        
        // Always clean up unmanaged resources
        // (native handles, pointers, raw system resources)
        this.disposeUnmanagedResources();
        
        // Mark as disposed AFTER cleanup completes
        this._isDisposed = true;
    }
    
    /**
     * Override in subclasses to clean up managed resources.
     * Only called when disposing=true (explicit disposal, not finalizer).
     */
    protected disposeManagedResources(): void {
        // Subclasses override this
    }
    
    /**
     * Override in subclasses to clean up unmanaged resources.
     * Called both from dispose() and from finalizer (if implemented).
     */
    protected disposeUnmanagedResources(): void {
        // Subclasses override this
    }
    
    /**
     * Guard method for checking disposal before operations.
     * Call this at the start of methods that require live resources.
     */
    protected throwIfDisposed(): void {
        if (this._isDisposed) {
            throw new ObjectDisposedException(this.constructor.name);
        }
    }
}
 
/**
 * Concrete example: A file handler with both managed and unmanaged resources
 */
class FileHandler extends DisposableBase {
    private fileHandle: NativeFileHandle | null;       // Unmanaged resource
    private bufferWriter: BufferWriter | null;         // Managed (Disposable) resource
    private readonly filePath: string;
    
    constructor(filePath: string) {
        super();
        this.filePath = filePath;
        
        // Acquire resources
        this.fileHandle = NativeFileSystem.openFile(filePath);
        this.bufferWriter = new BufferWriter(this.fileHandle);
        
        console.log(`[FileHandler] Opened: ${filePath}`);
    }
    
    /**
     * Write data to the file.
     */
    public write(data: string): void {
        this.throwIfDisposed();  // Guard check
        this.bufferWriter!.write(data);
    }
    
    /**
     * Flush buffered data to disk.
     */
    public flush(): void {
        this.throwIfDisposed();
        this.bufferWriter!.flush();
    }
    
    /**
     * Clean up managed resources (other Disposable objects).
     */
    protected override disposeManagedResources(): void {
        // Dispose BufferWriter first (it may hold references to fileHandle)
        if (this.bufferWriter !== null) {
            try {
                this.bufferWriter.dispose();
            } catch (e) {
                console.error("[FileHandler] Error disposing buffer:", e);
            }
            this.bufferWriter = null;
        }
        
        super.disposeManagedResources();
    }
    
    /**
     * Clean up unmanaged resources (native handles).
     */
    protected override disposeUnmanagedResources(): void {
        // Close the native file handle
        if (this.fileHandle !== null) {
            try {
                NativeFileSystem.closeFile(this.fileHandle);
                console.log(`[FileHandler] Closed: ${this.filePath}`);
            } catch (e) {
                console.error("[FileHandler] Error closing file handle:", e);
            }
            this.fileHandle = null;
        }
        
        super.disposeUnmanagedResources();
    }
}
 
class ObjectDisposedException extends Error {
    constructor(objectName: string) {
        super(`Cannot access disposed object: ${objectName}`);
        this.name = "ObjectDisposedException";
    }
}