Block Wrapping

Modules
	Feature Inhibition

Macros
#define	blkWrap(before, ...)   _blkStart _blkBeforeAfter(tokeval(before), __VA_ARGS__) _blkEnd

Detailed Description

Lightweight block wrapping macros for automatic cleanup and resource management.

The primary facility provided by this module is blkWrap(), which wraps a code block with "before" and "after" statements. The after statement is guaranteed to execute even if the block exits early with break or continue, making it ideal for resource management patterns similar to RAII in C++.

Common Use Cases:

// Mutex protection - automatic unlock even on early exit
blkWrap(mutexAcquire(&mtx), mutexRelease(&mtx)) {
    // critical section
    if (error) break;  // mutex still released
}
 
// Resource management - automatic cleanup
blkWrap(file = fopen("data.txt", "r"), fclose(file)) {
    if (!file) break;
    // use file
}
 
// Reference counting - automatic release
blkWrap(objAcquire(&obj), objRelease(&obj)) {
    // work with object
}

The framework uses these macros throughout for creating higher-level wrappers:

• withMutex(m) - Wraps mutex acquire/release
• withReadLock(l) and withWriteLock(l) - Wraps RWLock operations
• Many container iteration macros

Performance Characteristics:

Unlike protected blocks or exception handling, blkWrap() is very lightweight:

• Negligible runtime overhead
• Does not inhibit compiler optimizations
• Minimal stack space usage
• Suitable for performance-critical code

Compile-Time Feature Inhibition:

The module also provides compile-time checks to prevent misuse of certain language features within blocks. For example, return is inhibited in many block contexts to prevent resource leaks. In debug builds, using return where it's disallowed results in a compilation error.

Macro Definition Documentation

blkWrap

#define blkWrap	(		before,
			...
	)		_blkStart _blkBeforeAfter(tokeval(before), __VA_ARGS__) _blkEnd

blkWrap(before, after) { }

Wraps a code block with "before" and "after" statements, guaranteeing cleanup.

This is the primary facility for automatic resource management in CX. The before statement executes once when entering the block, and the after statement executes when leaving the block - either normally or via early exit with break or continue.

Key Features:

• Lightweight with negligible runtime overhead
• Does not inhibit compiler optimizations
• Minimal stack space usage
• break or continue at the base level will exit the block but still run cleanup
• return is not allowed within the block (compile error in debug builds)

Parameters

before	Statement to execute before the block
...	(after) Statement(s) to execute after the block (can use comma operator for multiple)

Common Patterns:

// Mutex protection
blkWrap(mutexAcquire(&mtx), mutexRelease(&mtx)) {
    // critical section
}
 
// Multiple cleanup operations
blkWrap(init(), (cleanup1(), cleanup2())) {
    // work
}
 
// Early exit still runs cleanup
blkWrap(acquire(), release()) {
    if (error) break;  // release() still called
    // more work
}

Used Throughout CX:

• withMutex(m) - Mutex acquire/release
• withReadLock(l), withWriteLock(l) - RWLock operations
  
• foreach and container iteration macros
• Many other resource management patterns

Note

For complex unwinding scenarios involving nested blocks, see Protected Blocks

Definition at line 225 of file block.h.