Implemented bli_acquire_mpart(), added example code.

Details:
- Implemented bli_acquire_mpart(), a general-purpose submatrix view
  function that will alias an obj_t to be a submatrix "view" of an
  existing obj_t.
- Renumbered examples in examples/oapi and inserted a new example file,
  03obj_view.c, which shows how to use bli_acquire_mpart() to obtain
  submatrix views of existing objects, which can then be used to
  indirectly modify the parent object.

examples/oapi/03obj_view.c

@@ -0,0 +1,272 @@
+/*
+
+   BLIS    
+   An object-based framework for developing high-performance BLAS-like
+   libraries.
+
+   Copyright (C) 2014, The University of Texas
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions are
+   met:
+    - Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    - Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    - Neither the name of The University of Texas nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+   HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+#include "blis.h"
+
+void init_dmatrix_by_rows( dim_t m, dim_t n, double* a, inc_t rs, inc_t cs );
+void init_dmatrix_by_cols( dim_t m, dim_t n, double* a, inc_t rs, inc_t cs );
+void init_dobj_by_cols( obj_t* a );
+void init_zobj_by_cols( obj_t* a );
+
+int main( int argc, char** argv )
+{
+	obj_t a1, a2;
+	obj_t v1, v2, v3, v4, v5;
+	num_t dt;
+	dim_t m, n;
+	inc_t rs, cs;
+	dim_t i, j;
+	dim_t mv, nv;
+
+	//
+	// This file demonstrates creating and submatrix views into existing matrices.
+	//
+
+	//
+	// Example 1: Create an object and then create a submatrix view.
+	//
+
+	printf( "\n#\n#  -- Example 1 --\n#\n\n" );
+
+	// We'll use these parameters for the following examples.
+	dt = BLIS_DOUBLE;
+	m = 6; n = 7; rs = 1; cs = m;
+
+	// Create an object a1 using bli_obj_create().
+	bli_obj_create( dt, m, n, rs, cs, &a1 );
+
+ 	// Initialize a1 to contain known values.
+	init_dobj_by_cols( &a1 )
+
+	bli_printm( "matrix 'a1' (initial state)", &a1, "%5.1f", "" );
+
+	// Acquire a 4x3 submatrix view into a1 at (i,j) offsets (1,2).
+	i = 1; j = 2; mv = 4; nv = 3;
+	bli_acquire_mpart( i, j, mv, nv, &a1, &v1 );
+
+	bli_printm( "4x3 submatrix 'v1' at offsets (1,2)", &v1, "%5.1f", "" );
+
+	// NOTE: Submatrix views should never be passed to bli_obj_free(). It
+	// will not cause an immediate error, but it is bad practice. Instead,
+	// you should only release the objects that were created directy via
+	// bli_obj_create(). In the above example, that means only object a1
+	// would be passed to bli_obj_free().
+
+	//
+	// Example 2: Modify the contents of a submatrix view.
+	//
+
+	printf( "\n#\n#  -- Example 2 --\n#\n\n" );
+
+	// Modify the first three elements of the first column.
+	bli_setijm( -3.0, 0.0, 0, 0, &v1 );
+	bli_setijm( -4.0, 0.0, 1, 0, &v1 );
+	bli_setijm( -5.0, 0.0, 2, 0, &v1 );
+
+	// Modify the first three elements of the second column.
+	bli_setijm( -6.0, 0.0, 0, 1, &v1 );
+	bli_setijm( -7.0, 0.0, 1, 1, &v1 );
+	bli_setijm( -8.0, 0.0, 2, 1, &v1 );
+
+	// Print the matrix again so we can see the update elements.
+	bli_printm( "submatrix view 'v1' (modified state)", &v1, "%5.1f", "" );
+	bli_printm( "matrix 'a1' (indirectly modified due to changes to 'v1')", &a1, "%5.1f", "" );
+
+	//
+	// Example 3: Create a submatrix view that is "too big".
+	//
+
+	printf( "\n#\n#  -- Example 3 --\n#\n\n" );
+
+	// bli_acquire_mpart() will safely truncate your requested submatrix
+	// view dimensions (or even the offsets) if they extend beyond the
+	// bounds of the parent object.
+
+	bli_printm( "matrix 'a1' (current state)", &a1, "%5.1f", "" );
+
+	// Acquire a 4x3 submatrix view into a1 at offsets (4,2). Notice how
+	// the requested view contains four rows, but the view is created with
+	// only two rows because the starting m offset of 4 leaves only two rows
+	// left in the parent matrix.
+	bli_acquire_mpart( 4, 2, 4, 3, &a1, &v2 );
+
+	bli_printm( "4x3 submatrix 'v2' at offsets (4,2) -- two rows truncated for safety", &v2, "%5.1f", "" );
+
+	//
+	// Example 4: Create a bufferless object, attach an external buffer, and
+	//            then create a submatrix view.
+	//
+
+	printf( "\n#\n#  -- Example 4 --\n#\n\n" );
+
+	// Create a object with known elements using the same approach as the
+	// previous example file.
+	double* p1 = malloc( m * n * sizeof( double ) );
+	init_dmatrix_by_cols( m, n, p1, rs, cs );
+	bli_obj_create_with_attached_buffer( dt, m, n, p1, rs, cs, &a2 );
+
+	bli_printm( "matrix 'a2' (initial state)", &a2, "%5.1f", "" );
+
+	// Acquire a 3x4 submatrix view at offset (2,3).
+	bli_acquire_mpart( 2, 3, 3, 4, &a2, &v3 );
+
+	bli_printm( "3x4 submatrix view 'v3' at offsets (2,3)", &v3, "%5.1f", "" );
+
+	//
+	// Example 5: Use a submatrix view to set a region of a larger matrix to
+	//            zero.
+	//
+
+	printf( "\n#\n#  -- Example 5 --\n#\n\n" );
+
+	bli_printm( "3x4 submatrix view 'v3' at offsets (2,3)", &v3, "%5.1f", "" );
+
+	bli_setm( &BLIS_ZERO, &v3 );
+
+	bli_printm( "3x4 submatrix view 'v3' (zeroed out)", &v3, "%5.1f", "" );
+
+	bli_printm( "matrix 'a2' (modified state)", &a2, "%5.1f", "" );
+
+	//
+	// Example 6: Obtain a submatrix view into a submatrix view.
+	//
+
+	printf( "\n#\n#  -- Example 6 --\n#\n\n" );
+
+	bli_acquire_mpart( 1, 1, 5, 6, &a2, &v4 );
+
+	bli_printm( "5x6 submatrix view 'v4' at offsets (1,1) of 'a2'", &v4, "%5.1f", "" );
+
+	bli_acquire_mpart( 1, 0, 4, 5, &v4, &v5 );
+
+	bli_printm( "4x5 submatrix view 'v5' at offsets (1,0) of 'v4'", &v5, "%5.1f", "" );
+
+
+	// Free the memory arrays we allocated.
+	free( p1 );
+
+	// Free the objects we created.
+	bli_obj_free( &a1 );
+
+	return 0;
+}
+
+// -----------------------------------------------------------------------------
+
+void init_dmatrix_by_rows( dim_t m, dim_t n, double* a, inc_t rs, inc_t cs )
+{
+	dim_t  i, j;
+
+	double alpha = 0.0;
+
+	// Step through a matrix by rows, assigning each element a unique
+	// value, starting at 0.
+	for ( i = 0; i < m; ++i )
+	{
+		for ( j = 0; j < n; ++j )
+		{
+			double* a_ij = a + i*rs + j*cs;
+
+			*a_ij = alpha;
+
+			alpha += 1.0;
+		}
+	}
+}
+
+void init_dmatrix_by_cols( dim_t m, dim_t n, double* a, inc_t rs, inc_t cs )
+{
+	dim_t  i, j;
+
+	double alpha = 0.0;
+
+	// Step through a matrix by columns, assigning each element a unique
+	// value, starting at 0.
+	for ( j = 0; j < n; ++j )
+	{
+		for ( i = 0; i < m; ++i )
+		{
+			double* a_ij = a + i*rs + j*cs;
+
+			*a_ij = alpha;
+
+			alpha += 1.0;
+		}
+	}
+}
+
+void init_dobj_by_cols( obj_t* a )
+{
+	dim_t m = bli_obj_length( a );
+	dim_t n = bli_obj_width( a );
+	dim_t i, j;
+
+	double alpha = 0.0;
+
+	// Step through a matrix by columns, assigning each element a unique
+	// value, starting at 0.
+	for ( j = 0; j < n; ++j )
+	{
+		for ( i = 0; i < m; ++i )
+		{
+			bli_setijm( alpha, 0.0, i, j, a );
+
+			alpha += 1.0;
+		}
+	}
+}
+
+void init_zobj_by_cols( obj_t* a )
+{
+	dim_t m = bli_obj_length( a );
+	dim_t n = bli_obj_width( a );
+	dim_t i, j;
+
+	double alpha = 0.0;
+
+	// Step through a matrix by columns, assigning each real and imaginary
+	// element a unique value, starting at 0.
+	for ( j = 0; j < n; ++j )
+	{
+		for ( i = 0; i < m; ++i )
+		{
+			bli_setijm( alpha, alpha + 1.0, i, j, a );
+
+			alpha += 2.0;
+		}
+	}
+}
+

examples/oapi/Makefile

@@ -105,16 +105,17 @@ CFLAGS         += -I$(TEST_SRC_PATH)
 LIBBLIS_LINK   := $(BUILD_PATH)/$(LIBBLIS_LINK)
 
 # Binary executable name.
-TEST_BINS      := 0obj_basic.x \
-                  1obj_attach.x \
-                  2obj_ij.x \
-                  3level0.x \
-                  4level1v.x \
-                  5level1m.x \
-                  6level1m_diag.x \
-                  7level2.x \
-                  8level3.x \
-                  9util.x
+TEST_BINS      := 00obj_basic.x \
+                  01obj_attach.x \
+                  02obj_ij.x \
+                  03obj_view.x \
+                  04level0.x \
+                  05level1v.x \
+                  06level1m.x \
+                  07level1m_diag.x \
+                  08level2.x \
+                  09level3.x \
+                  10util.x
 
 
 

examples/oapi/README

@@ -6,7 +6,7 @@ This directory contains several files, each containing various pieces of
 example code that demonstrate core functionality of the object API in BLIS.
 These example files should be thought of collectively like a tutorial, and
 therefore it is recommended to start from the beginning (the file that
-starts in '0').
+starts in '00').
 
 You can build all of the examples by simply running 'make' from this
 directory. (You can also run 'make clean'.) The makefile assumes that