Changeset 4208 for trunk/doc/pslib/psLibSDRS.tex
- Timestamp:
- Jun 9, 2005, 5:56:03 PM (21 years ago)
- File:
-
- 1 edited
-
trunk/doc/pslib/psLibSDRS.tex (modified) (19 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/pslib/psLibSDRS.tex
r4199 r4208 1 %%% $Id: psLibSDRS.tex,v 1.27 3 2005-06-09 22:21:06 jhoblittExp $1 %%% $Id: psLibSDRS.tex,v 1.274 2005-06-10 03:56:03 price Exp $ 2 2 \documentclass[panstarrs,spec]{panstarrs} 3 3 … … 127 127 Library (GSL): 128 128 129 \href{www.gnu.org/software/gsl/}{\tt www.gnu.org/software/gsl} );129 \href{www.gnu.org/software/gsl/}{\tt www.gnu.org/software/gsl}; 130 130 131 131 \item The sort functions should wrap the system \code{qsort} call … … 145 145 fashion in the Pilot Project. Also, RHL has provided functional 146 146 prototype code for the memory management, tracing and message logging 147 functions (some of which need to be revised), and the data containers148 (doubly-linked lists, hashes, arrays).147 functions (some of which need to be revised), and some of the data 148 containers (doubly-linked lists, hashes, arrays). 149 149 150 150 \subsection{Threads} 151 151 152 Pan-STARRS does not have a strong requirement for multithreading capability. 153 The memory management functions, defined below, must be written to be 154 thread-safe. The use of \code{static} variables should be keep to an absolute 155 minimum and then only when protected by a ``mutex''. Cross-thread 156 synchronization for PSLib's fundamental datatypes (\code{psArray}, 157 \code{psVector}, etc.) is left as an exercise for the end-user. 152 Pan-STARRS does not have a strong requirement for multithreading 153 capability. The memory management functions, defined below, must be 154 written to be thread-safe. The use of \code{static} variables should 155 be kept to an absolute minimum and then only when protected by a 156 ``mutex''. Cross-thread synchronization for PSLib's fundamental 157 datatypes (\code{psArray}, \code{psList}, etc.) is left to the end-user. 158 159 PSLib shall provide some functions and structures that assist in 160 thread-safety, but it is left up to the end-user to employ these. 161 That is, these conveniences are not used internally by PSLib, and so 162 the user should make no assumptions about thread-safety (outside the 163 memory management functions). 158 164 159 165 \subsection{Conventions} … … 204 210 \subsection{Initialization} 205 211 206 PSLib shallbe initialized by calling \code{psLibInit} by the user212 PSLib may be initialized by calling \code{psLibInit} by the user 207 213 before use. This enables the library to perform the following tasks 208 214 that are required before general use: … … 219 225 220 226 \code{timeConfig} specifies the filename of the configuration file 221 for \code{psTime} metadata 227 for \code{psTime} metadata. 222 228 223 229 \subsection{Finalization} … … 228 234 229 235 \code{psLibCleanup} shall free memory that was allocated by 230 \code{psLibInit}, allowing a subsequent search for leaked memory. 236 \code{psLibInit}, allowing a subsequent search for leaked memory (even 237 memory marked as \code{persistent}). 231 238 232 239 \subsection{Memory Management} … … 272 279 \item 273 280 While debugging complex scientific code, it is very useful to be 274 able to trace a givendata structure as it passes through the281 able to trace a specific data structure as it passes through the 275 282 processing pipeline. 276 283 … … 359 366 list. 360 367 361 The element \code{freeFunc} specifies the deallocator associated with a 362 specific block of memory. If this element is \code{NULL}, the basic 363 deallocator is used and the memory block must not be a rich data 364 structure which requires additional freeing functionality. 368 The element \code{freeFunc} specifies the deallocator associated with 369 a specific block of memory. If this element is \code{NULL}, the basic 370 deallocator (\code{psFree}) is used and the memory block must not be a 371 rich data structure which requires additional freeing functionality 372 (otherwise memory leaks will occur). 365 373 366 374 The element \code{id} in the structure is a sequential memory block … … 384 392 \code{persistent} to be ignored when identifing memory leaks with 385 393 \code{psMemCheckLeaks}. Private functions shall be provided to test 386 and set the value of \code{persistent}. 394 and set the value of \code{persistent}: 395 \begin{prototype} 396 void p_psMemSetPersistent(psPtr ptr, bool value); 397 bool p_psMemGetPersistent(psPtr ptr); 398 \end{prototype} 399 387 400 388 401 The \code{psMemBlock} structure element \code{refCounter} is provided … … 417 430 components that employ any \code{persistent} memory shall provide a 418 431 function that frees all of its \code{persistent} memory (and only that 419 persistent memory that belongs to that component). 432 persistent memory that belongs to that component), all of which should 433 be called from \code{psLibCleanup}. 420 434 421 435 \subsubsection{APIs for Allocating and Freeing} … … 768 782 points to a data block with multiple references, this call would only 769 783 decrement the counter. 784 785 \subsection{Conventions adopted} 786 787 Only pointers allocated with the PSLib memory functions are compatible 788 with the various PSLib container types (e.g., \code{psList, 789 psMetadata}), because the functions working with the container types 790 search for the attached \code{psMemBlock}. If a pointer allocated 791 with another memory system (e.g., the system \code{malloc}), or 792 generated by offsetting from another pointer that was allocated with 793 \code{psAlloc}, is used with PSLib, the PSLib functions would falsely 794 determine that memory is corrupted, because of the missing 795 \code{psMemBlock}. 796 797 To pilot our way through the potential confusion, instead of calling 798 all pointers (of unspecified type) a ``\code{void*}'', we adopt a 799 convention, both in this document and in the source, of referring to a 800 pointer that has a \code{psMemBlock} attached as a \code{psPtr}: 801 802 \begin{datatype} 803 typedef void* psPtr; 804 \end{dataType} 805 806 For the same reason, we also adopt a convention of referring to a string 807 that has a \code{psMemBlock} attached as a \code{psString}: 808 809 \begin{datatype} 810 typedef char* psString; 811 \end{datatype} 812 813 That is, \code{psPtr} is used in cases where the function requires the 814 use of a pointer of unspecified type allocated with \code{psAlloc}, 815 and \code{psString} is used in cases where the function requires the 816 use of a \code{char*} allocated with \code{psAlloc} (e.g., via 817 \code{psStringCopy} or \code{psStringNCopy}). 818 819 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 820 821 \subsection{Threads} 822 823 As pointed out earlier, PSLib makes no guarantees for thread-safety 824 outside of the memory management functions. Nevertheless, the following 825 facilities are provided as a convenience to the user. 826 827 Each of the data structures classified as a ``collection'' (i.e., 828 \code{psList, psHash, psMetadata, psArray, psPixels, psVector, 829 psBitSet}) and \code{psImage} shall contain an additional member, 830 \code{void *lock}, which provides a place for the user to carry around 831 a mutex or semaphore. This is provided so that the user doesn't have 832 to pass around both the structure and a mutex, or wrap PSLib 833 structures in their own thread-safe structures that contain a mutex. 834 835 We also define the following conveniences: 836 \begin{datatype} 837 typedef struct { 838 pthread_mutex_t mutex; 839 } psMutex; 840 \end{datatype} 841 842 \begin{prototype} 843 psMutex *psMutexAlloc(void); 844 bool psMutexLock(psMutex *mutex); 845 bool psMutexUnlock(psMutex *mutex); 846 \end{prototype} 847 848 \code{psMutex} simply wraps a POSIX thread mutex (this is necessary in 849 order to use the PS memory management system). 850 851 \code{psMutexAlloc} shall allocate memory for a \code{psMutex}, and 852 initialise the mutex. \code{psMutexLock} shall lock the mutex in 853 \code{thread}, and \code{psMutexUnlock} shall unlock the mutex in 854 \code{thread}. No distinction is made between read and write locks. 855 856 These functions, in the interests of speed, should be implemented as 857 preprocessor macros. 858 859 These functions should only be defined if \code{_REENTRANT} is 860 defined, and poisoned otherwise. 861 862 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 770 863 771 864 \subsection{Tracing and Logging} … … 1511 1604 psC64 *C64; ///< Pointers to complex floating-point data 1512 1605 } data; 1606 void *lock; ///< Lock for thread safety 1513 1607 } psVector; 1514 1608 \end{datatype} … … 1625 1719 const struct psImage *parent; ///< parent, if a subimage 1626 1720 psArray *children; ///< children of this region 1721 void *lock; ///< Lock for thread safety 1627 1722 } psImage; 1628 1723 \end{datatype} … … 1756 1851 const psU32 nalloc; // Number allocated 1757 1852 psPixelCoord *data; // The pixel coordinates 1853 void *lock; ///< Lock for thread safety 1758 1854 } psPixels; 1759 1855 \end{datatype} … … 1833 1929 const long nalloc; ///< allocated data block 1834 1930 void **data; ///< pointer to data block 1835 } psArray; 1931 void *lock; ///< Optional lock for thread safety 1932 }} psArray; 1836 1933 \end{datatype} 1837 1934 % … … 1918 2015 psListElem *tail; ///< last element on list (may be NULL) 1919 2016 psArray *iterators; ///< array of psListIterator: iteration cursors 2017 void *lock; ///< Optional lock for thread safety 1920 2018 } psList; 1921 2019 \end{datatype} … … 2126 2224 long n; ///< number of buckets 2127 2225 psHashBucket **buckets; ///< the buckets themselves 2128 } psHash; 2226 void *lock; ///< Optional lock for thread safety 2227 }} psHash; 2129 2228 \end{datatype} 2130 2229 % … … 2334 2433 long n; ///< Number of chars that form the bitset 2335 2434 char *bits; ///< The bits 2336 } psBitSet; 2435 void *lock; ///< Optional lock for thread safety 2436 }} psBitSet; 2337 2437 \end{datatype} 2338 2438 … … 2561 2661 psList *list; ///< list of psMetadataItem 2562 2662 psHash *hash; ///< hash table of the same metadata 2563 } psMetadata; 2663 void *lock; ///< Optional lock for thread safety 2664 }} psMetadata; 2564 2665 \end{datatype} 2565 2666 The type \code{psMetadata} is a container class for metadata. Note
Note:
See TracChangeset
for help on using the changeset viewer.
