File Exchange

image thumbnail

SHAREDCHILD creates a shared data copy of contiguous subset

version 4.00 (80.9 KB) by James Tursa
SHAREDCHILD creates a shared data copy of a contiguous subsection of an existing variable

4 Downloads

Updated 20 May 2019

View License

SHAREDCHILD creates a shared data copy of a contiguous subarray of an existing variable. The motivation for creating this mex routine is to have the ability to effectively create a reference to a contiguous sub-section of a variable without needing to create a deep data copy. For very large variables, this can have obvious benefits instead of creating a deep data copy that would be required at the m-code level.
EXAMPLES of using real & imag parts:

>> x = reshape(1:24,2,3,4) - reshape(1:24,2,3,4)*1i % Arbitrary 3D complex
x(:,:,1) =
1.0000 - 1.0000i 3.0000 - 3.0000i 5.0000 - 5.0000i
2.0000 - 2.0000i 4.0000 - 4.0000i 6.0000 - 6.0000i
x(:,:,2) =
7.0000 - 7.0000i 9.0000 - 9.0000i 11.0000 -11.0000i
8.0000 - 8.0000i 10.0000 -10.0000i 12.0000 -12.0000i
x(:,:,3) =
13.0000 -13.0000i 15.0000 -15.0000i 17.0000 -17.0000i
14.0000 -14.0000i 16.0000 -16.0000i 18.0000 -18.0000i
x(:,:,4) =
19.0000 -19.0000i 21.0000 -21.0000i 23.0000 -23.0000i
20.0000 -20.0000i 22.0000 -22.0000i 24.0000 -24.0000i

>> s = sharedchild(x,[1 2 1],[2 3 1]) % Rectangular child
s =
3.0000 - 3.0000i 5.0000 - 5.0000i
4.0000 - 4.0000i 6.0000 - 6.0000i

>> t = sharedchild(s,'ir') % Swapped real & imag version of s
t =
-3.0000 + 3.0000i -5.0000 + 5.0000i
-4.0000 + 4.0000i -6.0000 + 6.0000i

>> c = sharedchild(x,[2 1 3],[2 2 4],'i') % Not nD rectangle, so row
c =
-14 -15 -16 -17 -18 -19 -20 -21 -22

>> r = sharedchild(c,'rr').' % Real part of c used for real & imag parts of r
r =
-14.0000 -14.0000i
-15.0000 -15.0000i
-16.0000 -16.0000i
-17.0000 -17.0000i
-18.0000 -18.0000i
-19.0000 -19.0000i
-20.0000 -20.0000i
-21.0000 -21.0000i
-22.0000 -22.0000i

For the R2018a version, note that MATLAB now uses interleaved real/imag data instead of separate real/imag data. This means you can no longer mix & match real & imag parts to create the child subarrays as shown above. What you *can* do in R2018a is reinterpret real variables as complex variables (with 1/2 the number of elements as the source), and you can reinterpret complex variables as real variables (with 2x the number of elements as the source). The sharedchild_test function has added tests for this functionality, as well as tests for the real2complex and complex2real mex routines (see next paragraph).

Also added for the R2018a version are the standalone mex routines real2complex and complex2real. These are simple bare-bones mex routines that reinterpret real variables as complex (with first dimension halved) and complex variables as real (with first dimension doubled) respectively. They always operate on the whole variables, always return shared data copies, and do not require any persistent variables being held inside the mex routines. They can only be used with full variables (the sparse storage format is incompatible with this). They don't really provide any additional functionality that is not already present in sharedchild. Their main purpose is to provide mex programmers example code for how to do these tasks in the simplest way possible without all of the extra baggage contained in sharedchild.

*** DISCLAIMER ***

This mex routine uses undocumented API functions and hacks into the mxArray itself in order to create the child shared data copy. I have tried to code it in such a way that the routine will not crash MATLAB, but caveat emptor. In particular, the child variable that is returned from this mex routine is actually an invalid mxArray variable. The data pointers of the child are invalid since they point to the interior of an allocated memory block. This mex routine attempts to keep MATLAB from ever trying to free the memory behind these data pointers directly. All that being said, the rules for how MATLAB uses data pointers are not published, so I cannot guarantee that this mex routine will not crash MATLAB in some circumstances. Also, the hacks that this mex routine uses to create and manage these invalid child variables may not play nice with other mex routines using similar hacks. Updated and tested for various 32-bit and 64-bit MATLAB PCWIN versions R2011a - R2018a. Note that isempty( ) will not work in R2015b+ for emptied variables for some unknown reason (this was the primary cause of the testing failures in version 1.0). And numel( ) will crash MATLAB for emptied variables in R2015b (also for some unknown reason). It is suggested to manually clear the child subarray variables or 'UNSHARE' them rather than using the 'EMPTY' option if at all possible.

If you encounter a crash, please contact the author.

Cite As

James Tursa (2019). SHAREDCHILD creates a shared data copy of contiguous subset (https://www.mathworks.com/matlabcentral/fileexchange/65842-sharedchild-creates-a-shared-data-copy-of-contiguous-subset), MATLAB Central File Exchange. Retrieved .

Comments and Ratings (7)

Greg Janik

Greg Janik

James Tursa

Note that for R2018a and later, MATLAB stores complex data interleaved. Because of this, you cannot mix & match real and imag parts in R2018a and later like you can in R2017b and earlier.

James Tursa

64-bit version is in testing and I will probably upload it this week.

Tom DeLonge

is it 64-bit compatible yet?

James Tursa

Current 1.00 version does not work with 64-bit MATLAB ... at least some of the features. Update for 64-bit version is in work but will probably take at least a couple of weeks to complete and upload.

Updates

4.00

Updated for R2019a

3.10

Added real2complex and complex2real functions (reinterpret real->complex or complex->real shared data copy)

3.01

Fixed bug in R2018a 'R' and 'C' mode dimensions

3.0.0.0

Updated for R2018a

2.1.0.0

Fixed bug in 'end' indexing check

2.0.0.0

Updated and tested for various 32-bit and 64-bit MATLAB PCWIN versions R2011a - R2017b.

MATLAB Release Compatibility
Created with R2011a
Compatible with R2011a to R2018b
Platform Compatibility
Windows macOS Linux
Acknowledgements

Inspired by: InplaceArray: a semi-pointer package for Matlab