[Pntool-developers] SF.net SVN: pntool:[234] spnbox
Brought to you by:
compaqdrew,
miordache
Menu
▾
▴
[Pntool-developers] SF.net SVN: pntool:[234] spnbox
|
From: <Ste...@us...> - 2009-08-23 03:54:58
|
Revision: 234
http://pntool.svn.sourceforge.net/pntool/?rev=234&view=rev
Author: StephenCamp
Date: 2009-08-23 03:54:50 +0000 (Sun, 23 Aug 2009)
Log Message:
-----------
spnbox documentation added.
Added Paths:
-----------
spnbox/doc/
spnbox/doc/README.txt
spnbox/doc/functions.html
spnbox/doc/index.html
spnbox/doc/isis-2002-003.pdf
spnbox/doc/support.html
spnbox/doc/test.html
Removed Paths:
-------------
spnbox/README.txt
Deleted: spnbox/README.txt
===================================================================
--- spnbox/README.txt 2009-08-21 22:43:53 UTC (rev 233)
+++ spnbox/README.txt 2009-08-23 03:54:50 UTC (rev 234)
@@ -1,119 +0,0 @@
-#ABOUT
-SPNBOX implements the Petri net supervisory control functions originally developed
-for Matlab by Dr. Marian V. Iordache.
-
-The functions were converted to C for use with the ACTS tool by Stephen Camp.
-
-#COMPILING
-To generate object files for the entire SPNBOX toolset, run "make" from the
-pntool/spnbox directory.
-
-Note that SPNBOX makes use of the LPSOLVE MILP solver API found in the
-pntool/third-party directory. The makefile will attempt to copy the compiled
-library liblpsolve55.a from the LPSOLVE directories into the pntool/spnbox
-directory if it is not already present. If the LPSOLVE library is not present in
-its own directory, the SPNBOX makefile will invoke LPSOLVE's linux-targeted
-makefile to build the lpsolve library.
-
-#TESTING
-The subdirectory "tests" contains test files for the SPNBOX functions. There are
-source files for a test program for each function except chkcons, which is used
-as a subroutine of other functions and so tested implicitly.
-The makefile within the directory will make any of the test programs. To generate
-the test program for a particular function, use a command of the form:
-make <functionname>
-This will generate an executable called <functionname>.exe.
-Note that the makefile can be configured to include a set of debugging routines
-from the third-party library memwatch that will aid in debugging memory errors.
-See MEMORY DEBUGGING later in this file for more information. To include this
-library, the "USEMEMWATCH" variable in the test makefile should be set to "yes".
-If it is set to anything else the memory debugging routines will not be included.
-
-make all will generate test executables for all spnbox functions.
-
-To test the various functions in the matrixmath.c file, use make matrixmath. To
-test the functions in the extendedmatrix.c file, use make extendedmatrix.
-
-For all with such test programs except that ipslv, the test program is implemented
-as a program that will read from an input stream containing text in a human-
-readable format, interpret the text as parameters to the function, make a function
-call, and display the results. For format specifications, see the comments in
-StructuredIO.c/h.
-
-The programs may be invoked with a single command line argument, which will be
-taken as the name of a text file from which to read the input. If no command line
-argument is used the test programs will take input from the console.
-
-Pre-formatted test scripts with problems to test each part of a function have
-been provided. These are named in the form test-<functionname>.txt. There is no
-test script for admcon.c as the admcon function is thoroughly tested by its use
-within the dp function.
-
-Thus, to test ipsolve with the default test script the following command sequence
-might be issued:
-
-cd ~/pntool/spnbox/tests
-make ipsolve
-./ipsolve test-ipsolve.txt
-
-#MEMORY DEBUGGING
-The test makefile can compile and link the spnbox files so that their test
-routines will make use of the "memwatch" memory debugger. Memwatch is a set of
-routines, declared in memwatch.h in the pntool/third-party/memwatch-2.71/
-directory, that overrides the standard memory allocation and deallocation
-functions with its own wrappers.
-
-Memwatch keeps track of allocations and deallocations through its routines. It
-can detect some but not all array overwrites, underwrites, wild pointer writes,
-deallocations of invalid pointers, and various other potential errors related to
-dynamically allocated memory.
-
-When a program that contains the Memwatch routines runs it will create a text
-file in the current directory, titled memwatch.log by default, that lists any
-errors or anomalies detected by the memwatch routines.
-
-Note that the memwatch routines slow memory-related operations drastically.
-
-See pntool/third-party/memwatch-2.71/USING for more information.
-memwatch is licensed under the GNU public license, present in the file
-pntool/third-party/memwatch-2.71/gpl.txt.
-
-#FILES
-Main directory:
-- spnbox.h: This is the header file containing the definitions for all the SPNBOX
- functions, as well as various constant definitions.
-- matrixmath.h & matrixmath.c: These implement various matrix arithmetic operations
- used by other SPNBOX functions.
-- extendedmatrix.h & extendedmatrix.c: These implement operations to insert or
- remove rows and columns from matrices. Note that these functions employ when
- possible optimizations that rely heavily on the internal details of matrix
- implementation, and so if the matrix implementation is ever changed these
- files will need to be modified accordingly.
-- deallocation.c: This implements functions to deallocate the structures returned
- by SPNBOX functions.
-- Makefile: This is the main makefile. When used without a target it builds
- object files that implement all SPNBOX functionality.
- Use "make clean" to remove all object files, all library (*.a) files, and
- execute the clean command for the lpsolve library in the third-party/lp_solve_5.5
- directory.
- Use "make clean-partial" to remove all object files.
-- Each of the other files corresponds to a single SPNBOX function.
-
-tests subdirectory:
-- test.c & test.h: These define and implement a few subroutines used by many of
- the test programs as well as implemented the pntool "is_verbose" function to
- ensure maximum verbosity during testing. The header file also includes header
- files common to all the test programs.
-- StructuredIO.c & StructuredIO.h: These define and implement a pair of functions,
- ParseStructure and DisplayStructure. ParseStructure is used used to parse human-
- readable text from a stream as described in a format string and with it fill
- an arbitrary number of variables. It is an analogue of sprintf with support
- for more complex data structures such as arrays and matrices.
- DisplayStructure is used to display such data structures in a human-readable
- format as described by a similar format string. For usage and format string
- information see the comments in the files. These functions are used by nearly
- all the test programs to make the collection of input easier.
-- Makefile: This is the test makefile. It is responsible for building various
- test routines and takes targets as described above in #TESTING.
-- All other files are the source files for the test executables for various
- functions or the test scripts intended to be used with various text executables.
Added: spnbox/doc/README.txt
===================================================================
--- spnbox/doc/README.txt (rev 0)
+++ spnbox/doc/README.txt 2009-08-23 03:54:50 UTC (rev 234)
@@ -0,0 +1,119 @@
+#ABOUT
+SPNBOX implements the Petri net supervisory control functions originally developed
+for Matlab by Dr. Marian V. Iordache.
+
+The functions were converted to C for use with the ACTS tool by Stephen Camp.
+
+#COMPILING
+To generate object files for the entire SPNBOX toolset, run "make" from the
+pntool/spnbox directory.
+
+Note that SPNBOX makes use of the LPSOLVE MILP solver API found in the
+pntool/third-party directory. The makefile will attempt to copy the compiled
+library liblpsolve55.a from the LPSOLVE directories into the pntool/spnbox
+directory if it is not already present. If the LPSOLVE library is not present in
+its own directory, the SPNBOX makefile will invoke LPSOLVE's linux-targeted
+makefile to build the lpsolve library.
+
+#TESTING
+The subdirectory "tests" contains test files for the SPNBOX functions. There are
+source files for a test program for each function except chkcons, which is used
+as a subroutine of other functions and so tested implicitly.
+The makefile within the directory will make any of the test programs. To generate
+the test program for a particular function, use a command of the form:
+make <functionname>
+This will generate an executable called <functionname>.exe.
+Note that the makefile can be configured to include a set of debugging routines
+from the third-party library memwatch that will aid in debugging memory errors.
+See MEMORY DEBUGGING later in this file for more information. To include this
+library, the "USEMEMWATCH" variable in the test makefile should be set to "yes".
+If it is set to anything else the memory debugging routines will not be included.
+
+make all will generate test executables for all spnbox functions.
+
+To test the various functions in the matrixmath.c file, use make matrixmath. To
+test the functions in the extendedmatrix.c file, use make extendedmatrix.
+
+For all with such test programs except that ipslv, the test program is implemented
+as a program that will read from an input stream containing text in a human-
+readable format, interpret the text as parameters to the function, make a function
+call, and display the results. For format specifications, see the comments in
+StructuredIO.c/h.
+
+The programs may be invoked with a single command line argument, which will be
+taken as the name of a text file from which to read the input. If no command line
+argument is used the test programs will take input from the console.
+
+Pre-formatted test scripts with problems to test each part of a function have
+been provided. These are named in the form test-<functionname>.txt. There is no
+test script for admcon.c as the admcon function is thoroughly tested by its use
+within the dp function.
+
+Thus, to test ipsolve with the default test script the following command sequence
+might be issued:
+
+cd ~/pntool/spnbox/tests
+make ipsolve
+./ipsolve test-ipsolve.txt
+
+#MEMORY DEBUGGING
+The test makefile can compile and link the spnbox files so that their test
+routines will make use of the "memwatch" memory debugger. Memwatch is a set of
+routines, declared in memwatch.h in the pntool/third-party/memwatch-2.71/
+directory, that overrides the standard memory allocation and deallocation
+functions with its own wrappers.
+
+Memwatch keeps track of allocations and deallocations through its routines. It
+can detect some but not all array overwrites, underwrites, wild pointer writes,
+deallocations of invalid pointers, and various other potential errors related to
+dynamically allocated memory.
+
+When a program that contains the Memwatch routines runs it will create a text
+file in the current directory, titled memwatch.log by default, that lists any
+errors or anomalies detected by the memwatch routines.
+
+Note that the memwatch routines slow memory-related operations drastically.
+
+See pntool/third-party/memwatch-2.71/USING for more information.
+memwatch is licensed under the GNU public license, present in the file
+pntool/third-party/memwatch-2.71/gpl.txt.
+
+#FILES
+Main directory:
+- spnbox.h: This is the header file containing the definitions for all the SPNBOX
+ functions, as well as various constant definitions.
+- matrixmath.h & matrixmath.c: These implement various matrix arithmetic operations
+ used by other SPNBOX functions.
+- extendedmatrix.h & extendedmatrix.c: These implement operations to insert or
+ remove rows and columns from matrices. Note that these functions employ when
+ possible optimizations that rely heavily on the internal details of matrix
+ implementation, and so if the matrix implementation is ever changed these
+ files will need to be modified accordingly.
+- deallocation.c: This implements functions to deallocate the structures returned
+ by SPNBOX functions.
+- Makefile: This is the main makefile. When used without a target it builds
+ object files that implement all SPNBOX functionality.
+ Use "make clean" to remove all object files, all library (*.a) files, and
+ execute the clean command for the lpsolve library in the third-party/lp_solve_5.5
+ directory.
+ Use "make clean-partial" to remove all object files.
+- Each of the other files corresponds to a single SPNBOX function.
+
+tests subdirectory:
+- test.c & test.h: These define and implement a few subroutines used by many of
+ the test programs as well as implemented the pntool "is_verbose" function to
+ ensure maximum verbosity during testing. The header file also includes header
+ files common to all the test programs.
+- StructuredIO.c & StructuredIO.h: These define and implement a pair of functions,
+ ParseStructure and DisplayStructure. ParseStructure is used used to parse human-
+ readable text from a stream as described in a format string and with it fill
+ an arbitrary number of variables. It is an analogue of sprintf with support
+ for more complex data structures such as arrays and matrices.
+ DisplayStructure is used to display such data structures in a human-readable
+ format as described by a similar format string. For usage and format string
+ information see the comments in the files. These functions are used by nearly
+ all the test programs to make the collection of input easier.
+- Makefile: This is the test makefile. It is responsible for building various
+ test routines and takes targets as described above in #TESTING.
+- All other files are the source files for the test executables for various
+ functions or the test scripts intended to be used with various text executables.
Added: spnbox/doc/functions.html
===================================================================
--- spnbox/doc/functions.html (rev 0)
+++ spnbox/doc/functions.html 2009-08-23 03:54:50 UTC (rev 234)
@@ -0,0 +1,25 @@
+<html>
+<head>
+<title>SPNBOX Functions</title>
+</head>
+<body>
+<center><h3>SPNBOX Functions</h3></center>
+<a name="general"><b>General Information and Coding Conventions</b></a>
+<p>The SPNBOX functions are used for supervisory control. For descriptions of the purpose of individual functions see the <a href="isis-2002-003.pdf">original Matlab manual</a>. For descriptions of the C interfaces, see the <a href="../spnbox.h">spnbox header file</a>.</p>
+<p>There are common patterns in the way parameters are used. In general, matrices as defined in <a href="../../pnheaders/matrix.h">matrix.h</a> in the pntool directory are used to represent Petri net matrices, marking and other types of constraint matrices, and some vectors and are passed to SPNBOX functions by pointer. In general, vectors are represented as integer arrays and are passed to SPNBOX functions as pointers to ints. The size of an array is sometimes determined by context, as from the number of rows in matrix, and sometimes explicitly via an integer parameter.</p>
+<p>Return types use similar patterns. Matrices and vectors are represented in similar manners. In addition, some functions returns strings as status indications. The various status messages are defined in <a href="../spnbox.h">spnbox.h</a>. These messages are the same ones used in the original Matlab code.</p>
+<p>There are a few coding conventions used in the SPNBOX function implementations.</p>
+<ul>
+ <li>Most functions have been divided into subroutines, even where the functionality is only used once, to improve the readability of the code. In most files the subroutine division is a fairly natural division of the functionlity, but in a few places the Matlab functions did not lend themselves to obvious logical division. Here, the division into subroutines are somewhat arbitrary.</li>
+ <li>Almost every function has at least one subroutine, CheckParams, which checks the function parameters for validity and sometimes sets up defaults. It is typically this function that is responsible for raising an error (via merror defined in <a href="../../pnheaders/general.h">pnheaders/general.h</a>) and terminating.</li>
+ <li>The functions use a great deal of dynamic memory. Where numerous allocations or an unpredictable number of allocations are made, <a href="support.html#memorymanager">dynamic memory management routines</a> defined in the support files are used to record the allocations as they are made and free them all at the end of the function. Sometimes, however, the number of allocations is small enough that the management functions are not used.</li>
+ <li>All allocation is done via the safe wrappers tcalloc and tmalloc defined in <a href="../../pnheaders/general.h">general.h</a>.</li>
+</ul>
+<p>Some functions can print status messages to stdout during execution. How many of these messages will be printed is determined by a function int is_verbose(), declared but not implemented in <a href="../../pnheaders/general.h">general.h</a>. Verbosity is set by a custom implementation of the is_verbose() fuction. The integer returned by the function is the verbosity level. A higher level indicates a request to print more detail. The minimum, 0, means no message except those absolutely necessary should be printed. The maximum is 10. In the SPNBOX functions, each function has a verbosity threshold. It will print its messages only if the verbosity is at its threshold. Thresholds are defined in the main header file. Functions that are called by other functions should have a higher verbosity threshold so that their messages are displayed less readily.</p>
+<p><a href="../spnbox.h">spnbox.h</a> is the primary header file for the SPNBOX functions. It defines all the SPNBOX functions and all the necessary option macros, message strings, return type structures, and a few specialized parameter structures.</p>
+<br>
+<a name="building"><b>Building SPNBOX</b></a>
+<p>To build SPNBOX for use with ACTS, move to the pntool/spnbox/ directory and run make with the default target. This will build all object files for all the SPNBOX functions, as well as the support files used by them.</p>
+<p>Note that this will also check to make sure that the support file liblpsolve55.a, the compiled linear programming library, is present. If it is not, the makefile will change directories to the third-party directory where the lpsolve files reside and run its linux-targeted makefile.</p>
+</body>
+</html>
Added: spnbox/doc/index.html
===================================================================
--- spnbox/doc/index.html (rev 0)
+++ spnbox/doc/index.html 2009-08-23 03:54:50 UTC (rev 234)
@@ -0,0 +1,39 @@
+<html>
+<head>
+<title>SPNBOX for C</title>
+</head>
+<body>
+<center><h3>SPNBOX for C</h3></center>
+<p>SPNBOX is the suite of functions for supervisory control under ACTS, A Concurrency Tool Suite (see the <a href="http://pntool.sourceforge.net/">SourceForge project</a>). SPNBOX was originally developed by <a href="mailto:mar...@le...">Dr. Marian V. Iordache</a> for Matlab. SPNBOX for C is a conversion of the original Matlab functions into C, designed for use with the rest of ACTS. It was converted by <a href="mailto:ste...@le...">Stephen Camp</a>.</p>
+<p>The SPNBOX files are of three kinds: support files, functions used by the rest of the SPNBOX tools; the SPNBOX functions themselves, those which actually perform supervisory control; test files, used for creating demonstration executables, and the scripts that provide them with problems.</p>
+<p>In addition, the SPNBOX tools make use of the third-party LPSOLVE Linear Programming library. SPNBOX's use of LPSOLVE is discussed in detail in this documentation. LPSOLVE itself has its own <a href="../../third-party/lp_solve_5.5/doc/index.htm">here</a>.</p>
+<p>This documentation provides information about the files and functions primarily from a developer's perspective.</p>
+<center><h4>Index</h4></center>
+<ul>
+<li><b>SPNBOX Functions</b>
+ <ul>
+ <li><a href="functions.html#general">General Information and Coding Conventions</a></li>
+ <li><a href="functions.html#building">Building SPNBOX</a></li>
+ <li><a href="isis-2002-003.pdf">Original SPNBOX for Matlab Manual</a></li>
+ </ul>
+<li><b>Support Files</b>
+ <ul>
+ <li><a href="support.html#deallocation">Deallocation Functions (deallocation.c)</a></li>
+ <li><a href="support.html#extendedmatrix">Extended Matrix Manipulation (extendedmatrix.c)</a></li>
+ <li><a href="support.html#liblpsolve55">LP Solve Library (liblpsolve55.a)</a></li>
+ <li><a href="support.html#matrixmath">Matrix Arithmetic (matrixmath.c)</a></li>
+ <li><a href="support.html#memorymanager">Dynamic Memory Management (MemoryManager.c)</a></li>
+ </ul>
+</li>
+<li><b>Test Files</b>
+ <ul>
+ <li><a href="test.html#general">General Information and Coding Conventions</a></li>
+ <li><a href="test.html#building">Building Test Routines</a></li>
+ <li><a href="test.html#structuredio">High-Level I/O Routines (StructuredIO.c)</a></li>
+ <li><a href="test.html#memwatch">Third-Party Memory Debugging Library (memwatch.c)</a></li>
+ </li>
+ </ul>
+</li>
+</body>
+</html>
+
Added: spnbox/doc/isis-2002-003.pdf
===================================================================
(Binary files differ)
Property changes on: spnbox/doc/isis-2002-003.pdf
___________________________________________________________________
Added: svn:mime-type
+ application/octet-stream
Added: spnbox/doc/support.html
===================================================================
--- spnbox/doc/support.html (rev 0)
+++ spnbox/doc/support.html 2009-08-23 03:54:50 UTC (rev 234)
@@ -0,0 +1,22 @@
+<html>
+<head>
+<title>SPNBOX Support Files</title>
+</head>
+<body>
+<center><h3>SPNBOX Support Files</h3></center>
+<a name="deallocation"><b>Deallocation Functions (deallocation.c)</b></a>
+<p>deallocation.c implements a series of functions the purpose of which is to deallocate the various structures returned by the SPNBOX functions. It has been made as safe as possible - that is, it checks before attempting to free arrays to ensure that the array pointers are not null and before attempting to deallocate matrices to make sure that they have been allocated. This last check is implemented by examing the matrix type - a nonzero type is taken to be an indicator of a valid matrix. Thus, result structures should always be zeroed after they are created so that, if the structure should be passed to a deallocation function before it is filled by an SPNBOX function, the deallocation function will not attempt free some random piece of memory.</p>
+<a name="extendedmatrix"><b>Extended Matrix Manipulation (extendedmatrix.c)</b></a>
+<p>The extended matrix manipulation functions provide functionality above and beyond that of mere matrix arithmatic. The general parameter format is to take pointers to the operand matrices followed by any row and column numbers, possibly followed by an integer describing the mode. Most of the functions are such that their return value is a single matrix. The mode integer changes the behavior of the functions. Modes between 1 and 3 request that the returned matrix be a newly-allocated matrix of the given type and that the operands be left unaltered. A mode of 0 requests that the returned matrix be a newly-allocated matrix of the default type assigned by AllocateMatrix and the operands be left unaltered. A negative mode requests that the operand matrix (or the primary operand if there are several) be altered by the function and returned.</p>
+</p>Some of the functions, when in a negative mode, attempt to employ an optimization based on the internal nature of the matrix type. When the operation involves the addition, movement, or deletion of rows or columns, a type-2 matrix is of particular interest. The type-2 matrix stores its data as an array of arrays, that is, a pointer to an array of pointers, each of which is a pointer to an array of matrix elements. For an untransposed matrix (trans = 0), the sub-arrays are rows. For a transposed matrix (trans = 1) the sub-arrays are columns. Thus, if the operation in question deals with rows and the operand matrix or matrices are type-2 untransposed, the pointers to arrays can be manipulated rather than having to copy or reallocate areas of memory. Simililarly, if the operation deals with columns and the matrices are type-2 transposed, the pointers to arrays can be manipulated rather than having to reallocate or copy areas of memory. Note that these attempts at optimization are carried out internally and should be totally transparent to the calling function except where speed is concerned.</p>
+<p>For specific function descriptions see the header file, <a href="../extendedmatrix.h">extendedmatrix.h</a>.</p>
+<a name="liblpsolve55"><b>LP Solve Library (liblpsolve55.a)</b></a>
+<p>This is a third-party mixed integer linear programming solver used by SPNBOX. The SPNBOX functions all interface to it via <a href="../ipsolve.c">ipsolve.c</a>, which itself interfaces to the MILP library via <a href="../ipslv.c">ipslv.c</a>. This library file is the result of the linux-targeted <a href="../../third-party/lp_solve_5.5/Makefile.Linux">makefile</a> in the third-party/lp_solve_5.5 directory. The makefile is called by the SPNBOX makefile, which then copies the final library file liblpsolve55.a from its default location in the directory /third-party/lp_solve_5.5/lpsolve55/ to the /spnbox directory.</p>
+<a name="matrixmath"><b>Matrix Arithmetic (matrixmath.c)</b></a>
+<p>The matrix arithmetic functions, as well as a few utility functions such as transposition and a friendly display function, are contained in the <a href="../matrixmath.h">matrixmath.h</a> and .c files. The general format of these functions is to take as parameters pointers to the operand matrices, any integer operands, and finally a pointer to a matrix in which the result will be stored. The result is assumed to have already been allocated. The result matrix will typically also be returned by the arithmetic function. However, if the pointer to the destination matrix is replaced by an integer between 0 and 3, a new matrix of the correct size will be allocated, filled with the result, and returned. If the integer is set to 0 the default allocation type will be used. Otherwise the specified type will be used.</p>
+<a name="memorymanager"><b>Dynamic Memory Management (memorymanager.c)</b></a>
+<p>The memory management files define two structures as aids in memory management and the functions to work with them. <a href="../MemoryManager.h">MemoryManager.h</a> maintains a self-growing list of memory allocations and matrix allocations so that all the memory can be freed at once. Its accompanying functions are wrappers for the allocation functions, mcalloc and MAllocateMatrixType, which take as their first argument a pointer to a MemoryManager struct. They will allocate the new memory or matrix as requested and add a pointer to it to the appropriate lists. MemoryManagers hold separate lists, one for matrices and one for ordinary memory. The other functions are ManageMatrix and ManageMemory, which add to the lists matrices or pieces of memory that were not created through the wrapper functions but should be deallocated with the rest of the memory in the manager's lists. FreeMemory takes a pointer to a memory manager and will free all the memory and all the matrices. Note that, internally, it frees matrices first and then normal memory. MemoryManager keeps its lists in dynamically-allocated memory, which is reallocated in blocks and not reallocated again until the next entire block has been filled. The block size for the memory and matrix lists can be set separately via the function that creates Memory Managers, but if the relevant parameters are less than some minimum it will raise them to the minimum, which is blocks of 5.</p>
+<p>The other structure provided by MemoryManager.h is a MemoryGrower. This keeps track of a fixed number of pieces of memory, the number determined during creation by a parameter passed to CreateMemoryGrower. It allows these pieces of memory to be increased in size efficiently by allocating them in multiples of some block size, also determined during creation, and not actually reallocating until some amount of memory greater than the current actual capacity is requested. It does this by wrapping the allocation functions with its own, growMalloc and growCalloc, that take one additional parameter, a pointer to the MemoryGrower structure. They are used like variants of realloc, in that if the memory had been previously allocated they ensure that the previous contents remain.
+Note that MemoryGrower keeps track of capacity based on the value of the pointer associated with the memory. Thus an external change to this pointer value will cause a fatal error when MemoryGrower is unable to locate the new pointer in its record of managed pointers.</p>
+</body>
+</html>
Added: spnbox/doc/test.html
===================================================================
--- spnbox/doc/test.html (rev 0)
+++ spnbox/doc/test.html 2009-08-23 03:54:50 UTC (rev 234)
@@ -0,0 +1,31 @@
+<html>
+<head>
+<title>SPNBOX Test Files</title>
+</head>
+<body>
+<h3><center>SPNBOX Test Files</center></h3>
+<a name="general"><b>General Information and Coding Conventions</b></a>
+<p>The SPNBOX functions come with a set of test files used during debugging. The files are contained all contained in the /spnbox/tests/ directory. There are source files to produce one executable for each SPNBOX function. The executables take input from the console or from a file, specified as a single command-line argument.</p>
+<p>The input should be formatted to be interpreted by a special set of IO routines, discussed <a href="#structuredio">later</a>. Input should describe a single problem, that is, all the parameters for a call to the function the executable tests. When a particular keyword is given, each program displays a summary of the data it was given, makes a test call to the function it tests with the given parameters, and displays the result.</p>
+<p>The test programs typically use a single header file, <a href="../tests/test.h">test.h</a>, that includes all the header files that are typically used by a test program. This file also defines a few functions, implemented in <a href="../tests/test.c">test.c</a>, that are useful in many of the test programs.</p>
+<p>The first such function is <code>FILE* ParseCmdLine(int argc, char* argv[])</code>, which takes as parameters the same parameters used by an executable to retrieve its command-line arguments and returns a pointer to the stream which should be used for input. ParseCmdLine examines the arguments to the program. If there are any arguments the first is interpreted as a filename. ParseCmdLine attempts to open the file for input and return a pointer to it. If the open fails ParseCmdLine returns a null pointer. If there are no arguments, ParseCmdLine displays a message informing the user they may type "help" for information about commands and returns a pointer to stdin.</p>
+<p>Another such is FillDmDp. This function is useful in the context of the I/O routines because they make parameters optional and return an integer flag array to indicate which ones have been filled in. In order to allow users to enter either complete incidence matrices (more convenient since it contains the data in Dm and Dp in one matrix) or separate input and output matrices if the Petri net contains self-loops, the programs typically allow the user all three options and let them enter what they choose. FillDmDp examines three flags in an integer array, assuming that the flags represent the filled state of D, Dm, and Dp, and if D has been given will use the pns functions to fill Dm and Dp with the appropriate matrices.</p>
+<p>Finally, test.h defines <code>is_verbose()</code> to return the value of a global integer from <a href="../tests/test.c">test.c</a>. This integer can be set with a call to <code>void setverbose(int)</code>, defined in test.h & c.</p>
+<p>The general structure of a typical test program is to use <code>ParseCmdLine()</code> to retrieve a pointer to the input file. Then, an description of what variables are needed for that particular function type is placed in a string (character array). This description is in a format used internally by the specialized IO routines. Miscellaneous problem variables are defined here as well. The core of the program is a loop that continues until the function <code>ParseStructure()</code>, which uses the text description to read in variables for a single function call, returns 0, indicating that a keyword was found in the input stream requesting program termination. In the body of the loop, the variables filled by the <code>ParseStructure()</code> are displayed (written to stdout) and then formatted as necessary to prepare them for use in a call to the function being tested. The function call is made and the results are displayed. Memory allocated by the <code>ParseStructure()</code> call and in the function return value is freed. Then the loop returns to its beginning and <code>ParseStructure</code> is called again. At the end of the program any residual memory is freed.</p>
+<p>Note that there are a few routines for which the test program is different, and a few for which there is no test program because they are used subroutines of other thoroughly tested programs.</p>
+<p>In addition, test scripts have been provided for the test programs. These contain text in the correct format to test all the functionality of a given function. The naming convention is test-functionname.txt.<p>
+<a name="building"><b>Building Test Routines</b></a>
+<p>The makefile in the tests folder can make each of the executables to test each of the programs. Each executable is a single target, and each one has the name of the function being tested. Thus, to test ipsolve, one would use the following sequence of commands (beginning from the pntool root directory).</p>
+<code>
+cd spnbox/tests<br>
+make ipsolve<br>
+./ipsolve test-ipsolve.txt<br>
+</code>
+<p>Note that the makefile can, as an option, link in a third-party memory debugging library located in the /third-party/memwatch-2.71/ directory. This library wraps the memory allocation and deallocation functions and keeps track of allocations and frees. It also attempts to catch wild pointer writes and other memory-related errors. See the later section on memwatch for more information. The inclusion of this library in the test routines slows them down by orders of magnitude, so its inclusion is optional, set by the setting of the "USEMEMWATCH" variable which is defined in the first few lines of the test makefile. When this variable is set to "yes", the memwatch libraries will be included. When it is set to any other value they will be left out.</p>
+<a name="structuredio"><b>High Level I/O Routines (StructuredIO.c)</b></a>
+<p><a href="../tests/StructuredIO.h">StructuredIO.h</a> and .c define a pair of routines intended to read and display complex data such as matrices and vectors in a human-readable format. There are two functions.<p>
+<p><code>int ParseStructure(FILE *file, char* DataDescription, int** FilledMask, MemoryManager* Memory, ...)</code> is for reading in data. The first parameter is a file pointer to the stream from which input is to be taken. This can be stdin. DataDescription is a null-terminated string containing a description of the variables that define a single problem. This includes names, the keywords that will be used to indicate that a particular variable follows when they are encountered in the input stream, and the type of variable. For more information about the format of this string, see the comments in <a href="../tests/StructuredIO.h">StructuredIO.h</a>. The next parameter, FilledMask, is a pointer to an integer pointer that will be filled with an array allocated by <code>ParseStructure()</code>. There will be one element for each variable that is to possibly be filled, set to 0 if that variable was not found in the input stream before the end-of-problem keyword was encountered, and set to nonzero if the keyword was found and the variable was filled. The MemoryManager pointer points to a MemoryManager structure (which should have been previously initialized) which is used to record all the allocations made by the call to <code>ParseStructure()</code>. This is followed by optional parameters, pointers to variables corresponding to those defined in the DataDescription. The function reads the input stream looking for keywords, after which are assumed to come the values of the variables associated with those keywords. The data is read and put into the variables pointed to by the optional parameters. There are also several predefined keywords which cause <code>ParseStructure()</code> to perform other tasks. When the "echo" keyword is encountered the remainder of the line is read and printed to stdout. When "rem" is encountered the rest of the line is ignored. When "help" is encountered a message describing basic usage and whatever keywords have been set up by the DataDescription is printed - "help 'keyword'" returns help on a specific predefined keyword. "done" ends the current problem, causing <code>ParseStructure()</code> to return a nonzero value. "quit" is interpreted as a request to terminate the program, causeing <code>ParseStructure</code> to return zero. For more information about keywords and data formats see the <a href="../tests/StructuredIO.h">StructuredIO.h</a> header file.</p>
+<p>The second function, <code>void DisplayStructure(char* DataDescription, int* Mask, ...)</code> is used to display the same kinds of data as that read by <code>ParseStructure</code> in a friendly format. Similar parameters have similar meanings. For more information on how the data is displayed, see the <a href="../tests/StructuredIO.h">StructuredIO.h</a> header file.</p>
+<a name="memwatch"><b>Third-Party Member Debugging Library (memwatch.c)</b></a>
+<p>The memwatch library is a third-party library intended to help fing memory-related bugs such as wild frees, wild pointer writes, overwrites, and underwrites. It functions by wrapping C's memory functions with its own, which log allocations and deallocations, allocate buffers around allocated pieces of memory to detect overwrites and underwrites, and implements several other algorithms to help detect memory errors. Each time a program the libraries have been included in executes, memwatch creates (or appends to if it already exists) a log file, memwatch.log. This log file will include notes of any errors or anomolies the memwatch routines detect. Because the routines slow down any memory-related operations by orders of magnitude, their inclusion in the test routines is optional and can be enabled or disabled as described in the <a href="#building">"Building Test Routines"</a> section.</p>
+<p>More information on the memwatch routines can be found in several files, <a href="../../third-party/memwatch-2.71/README">/third-party/memwatch-2.71/README</a>, <a href="../../third-party/memwatch-2.71/USING">/third-party/memwatch-2.71/USING</a>, and in the primary header file, <a href="../../third-party/memwatch-2.71/memwatch.h">/third-party/memwatch-2.71/memwatch.h</a>.</p>
\ No newline at end of file
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
