Changeset 4254 for trunk/doc/pslib/psLibSDRS.tex
- Timestamp:
- Jun 14, 2005, 2:52:45 PM (21 years ago)
- File:
-
- 1 edited
-
trunk/doc/pslib/psLibSDRS.tex (modified) (30 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/pslib/psLibSDRS.tex
r4253 r4254 1 %%% $Id: psLibSDRS.tex,v 1.28 2 2005-06-15 00:30:28 eugene Exp $1 %%% $Id: psLibSDRS.tex,v 1.283 2005-06-15 00:52:45 price Exp $ 2 2 \documentclass[panstarrs,spec]{panstarrs} 3 3 … … 148 148 containers (doubly-linked lists, hashes, arrays). 149 149 150 \subsection{Threads} 151 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). 150 \subsection{Threads and Re-entrancy} 151 152 Due to current developments in CPU architecture, we must assume that 153 PSLib will be used in a threaded environment. However, coding the 154 library to be thread-safe may have implications for the speed of the 155 library and for the simplicity of use. We therefore make the 156 following policies: 157 158 \begin{itemize} 159 \item The memory management functions, defined below, must be written 160 to be thread-safe, since we cannot risk this crucial area being 161 unstable. 162 \item Re-entrant versions of system calls and external library 163 functions should be used. We expect that these cases are 164 sufficiently small that we are prepared to err on the side of 165 caution. 166 \item The practise of using \code{static} variable to achieve high 167 efficiency (e.g., so that subsequent calls do not have to repeat a 168 large memory allocation) should be kept to an absolute minimum. 169 Where it has been justified (i.e., through code profiling), the 170 \code{static} variable must be protected by a ``mutex''. 171 \item Cross-thread synchronization for PSLib's fundamental datatypes 172 (\code{psArray}, \code{psList}, etc.) is left to the end-user 173 (although some convenience is provided --- see below). 174 \end{itemize} 175 176 As a convenience to the user in achieving thread-safe operation, each 177 of the data structures classified as a ``collection'' (i.e., 178 \code{psList, psHash, psMetadata, psArray, psPixels, psVector, 179 psBitSet}) and \code{psImage} shall contain a member, \code{void 180 *lock}, which provides a place for the user to carry around a mutex or 181 semaphore. This is provided so that the user doesn't have to pass 182 around both the structure and a mutex, or wrap PSLib structures in 183 their own thread-safe structures that contain a mutex. PSLib is not 184 responsible for allocating, setting, checking or freeing the 185 \code{lock} --- these are entirely the responsibility of the user. 186 PSLib provides only a place to hang it. Your mileage may vary. 187 188 If these policies become a burden on the processing speed, we can 189 investigate alternative measures, such as defining specifically 190 re-entrant versions of select speed-critical functions. 164 191 165 192 \subsection{Angles} … … 343 370 struct psMemBlock* previousBlock; ///< previous block in allocation list 344 371 struct psMemBlock* nextBlock; ///< next block allocation list 345 psFreeFunc freeFunc; 372 psFreeFunc freeFunc; ///< deallocator. If NULL, use generic deallocation. 346 373 size_t userMemorySize; ///< the size of the user-portion of the memory block 347 374 const psMemId id; ///< a unique ID for this allocation 348 375 const char* file; ///< set from __FILE__ in e.g. p_psAlloc 349 376 const unsigned int lineno; ///< set from __LINE__ in e.g. p_psAlloc 350 pthread_mutex_t refCounterMutex;///< mutex to ensure exclusive access to reference counter377 pthread_mutex_t refCounterMutex; ///< mutex to ensure exclusive access to reference counter 351 378 psReferenceCount refCounter; ///< how many times pointer is referenced 352 379 bool persistent; ///< marks if non-user persistent data like error stack, etc. … … 787 814 \code{psStringCopy} or \code{psStringNCopy}). 788 815 816 \subsubsection{Strings} 817 818 The use of strings within the PSLib memory management system requires 819 that they be allocated with \code{psAlloc}. This means that 820 substrings cannot be placed on containers such as \code{psArray} or 821 \code{psMetadata}, since these check for the existence of the attached 822 \code{psMemBlock}. To get around this, we specify functions that copy 823 a string into \code{psAlloc}-ed memory: 824 \begin{prototype} 825 psString psStringCopy(const char *string); 826 psString psStringNCopy(const char *string, unsigned int nChar); 827 \end{prototype} 828 829 \code{psStringCopy} shall perform a deep copy of the \code{string} 830 into \code{psAlloc}-ed memory. \code{psStringNCopy} shall do the 831 same, up to a maximum of \code{nChar} characters. 832 833 We also specify two useful functions: 834 835 \begin{prototype} 836 ssize_t psStringAppend(char **dest, const char *format, ...) 837 ssize_t psStringPrepend(char **dest, const char *format, ...) 838 \end{prototype} 839 840 \code{psStringAppend} shall append, according to the \code{format} 841 values into the \code{dest} string. \code{dest} shall be allocated if 842 \code{NULL}, and the length of the new string (excluding the 843 terminator) shall be returned. \code{psStringPrepend} shall do 844 similarly, except it shall prepend to the \code{dest} string. 789 845 790 846 \subsubsection{Type information} … … 943 999 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 944 1000 945 \subsection{Threads} 946 947 As pointed out earlier, PSLib makes no guarantees for thread-safety 948 outside of the memory management functions. Nevertheless, the following 949 facilities are provided as a convenience to the user. 950 951 Each of the data structures classified as a ``collection'' (i.e., 952 \code{psList, psHash, psMetadata, psArray, psPixels, psVector, 953 psBitSet}) and \code{psImage} shall contain an additional member, 954 \code{void *lock}, which provides a place for the user to carry around 955 a mutex or semaphore. This is provided so that the user doesn't have 956 to pass around both the structure and a mutex, or wrap PSLib 957 structures in their own thread-safe structures that contain a mutex. 958 PSLib is not responsible for freeing the \code{lock} (it may not even 959 be allocated using the PSLib memory management system) --- it is 960 entirely the responsibility of the user and PSLib provides only a 961 place to hang it. 962 963 We also define the following conveniences: 964 \begin{datatype} 965 typedef struct { 966 pthread_mutex_t mutex; 967 } psMutex; 968 \end{datatype} 969 970 \begin{prototype} 971 psMutex *psMutexAlloc(void); 972 bool psMutexLock(psMutex *mutex); 973 bool psMutexUnlock(psMutex *mutex); 974 \end{prototype} 975 976 \code{psMutex} simply wraps a POSIX thread mutex (this is necessary in 977 order to use the PS memory management system). 978 979 \code{psMutexAlloc} shall allocate memory for a \code{psMutex}, and 980 initialise the mutex. \code{psMutexLock} shall lock the mutex in 981 \code{thread}, and \code{psMutexUnlock} shall unlock the mutex in 982 \code{thread}. 983 984 These functions, in the interests of speed, should be implemented as 985 preprocessor macros. 986 987 These functions and the \code{void *lock} in the collection structures 988 and \code{psImage} should only be defined if \code{_REENTRANT} is 989 defined; otherwise the functions should be poisoned. 1001 %%% 1002 %%% Not sure we need these --- all we do is wrap pthread_mutex, so why bother? 1003 %%% 1004 1005 %% \subsection{Locks} 1006 %% 1007 %% We define the following conveniences: 1008 %% \begin{datatype} 1009 %% typedef pthread_mutex_t psMutex; 1010 %% \end{datatype} 1011 %% 1012 %% \begin{prototype} 1013 %% psMutex *psMutexAlloc(void); 1014 %% bool psMutexLock(psMutex *mutex); 1015 %% bool psMutexUnlock(psMutex *mutex); 1016 %% \end{prototype} 1017 %% 1018 %% \code{psMutex} simply wraps a POSIX thread mutex (this is necessary in 1019 %% order to use the PS memory management system). 1020 %% 1021 %% \code{psMutexAlloc} shall allocate memory for a \code{psMutex}, and 1022 %% initialise the mutex. \code{psMutexLock} shall lock the \code{mutex}, 1023 %% and \code{psMutexUnlock} shall unlock the \code{mutex}. 1024 %% 1025 %% These functions, in the interests of speed, should be implemented as 1026 %% preprocessor macros. 1027 %% 1028 %% These functions and the \code{void *lock} in the collection structures 1029 %% and \code{psImage} should only be defined if \code{_REENTRANT} is 1030 %% defined; otherwise the functions should be poisoned. 990 1031 991 1032 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% … … 3095 3136 psC32 **C32; ///< Pointers to complex floating-point data 3096 3137 psC64 **C64; ///< Pointers to complex floating-point data 3097 3138 psPtr V; ///< Pointers to raw data 3098 3139 } data; 3099 3140 const struct psImage *parent; ///< parent, if a subimage … … 3796 3837 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 3797 3838 3839 \subsection{Masks} 3840 3841 Several functions --- especially the statistical and image functions 3842 --- use a mask vector and a mask value to specify values in an input 3843 list that should be excluded from the calculations. We define a mask 3844 type, which we will initially set to U8. In the event that our masks 3845 exceed eight bits, we can then change the mask definition without 3846 major changes throughout the code. 3847 3848 \begin{datatype} 3849 typedef psU8 psMask; 3850 \end{datatype} 3851 3798 3852 \subsection{Statistical Functions} 3799 3853 … … 3830 3884 const psVector *errors, 3831 3885 const psVector *mask, 3832 unsigned intmaskVal3886 psMask maskVal 3833 3887 ); 3834 3888 \end{prototype} … … 3859 3913 clipped statistics are modified according to the ADD; the robust 3860 3914 median and quartiles are modified as specified in the ADD. The mask 3861 must be of type \code{ps U8}.3915 must be of type \code{psMask}. 3862 3916 3863 3917 The \code{psStats} structure is defined with entries for each of the … … 3974 4028 const psVector *errors, 3975 4029 const psVector *mask, 3976 unsigned intmaskVal);4030 psMask maskVal); 3977 4031 \end{prototype} 3978 4032 The \code{values} vector may be of types \code{psU8, psU16, psF32, … … 4006 4060 typedef struct { 4007 4061 psPolynomialType type; ///< Polynomial type 4008 psElemType ctype; ///< Polynomial precision4062 psElemType ctype; ///< Polynomial precision 4009 4063 int n; ///< Number of terms 4010 4064 union { … … 4024 4078 typedef struct { 4025 4079 psPolynomialType type; ///< Polynomial type 4026 psElemType ctype; ///< Polynomial precision4080 psElemType ctype; ///< Polynomial precision 4027 4081 int nX, nY; ///< Number of terms in x and y 4028 4082 union { … … 4034 4088 psF64 **F64; ///< Error in coefficients 4035 4089 } coeffErr; 4036 char *mask; ///< Coefficient mask4037 4090 char **mask; ///< Coefficients mask 4038 4091 } psPolynomial2D; … … 4077 4130 psF64 x); 4078 4131 psF64 psPolynomial2DEval(const psPolynomial2D *poly, 4079 4080 4132 psF64 x, 4133 psF64 y); 4081 4134 psF64 psPolynomial3DEval(const psPolynomial2D *poly, 4082 4083 4084 4135 psF64 x, 4136 psF64 y, 4137 psF64 z); 4085 4138 psF64 psPolynomial4DEval(const psPolynomial2D *poly, 4086 4087 4088 4089 4139 psF64 x, 4140 psF64 y, 4141 psF64 z, 4142 psF64 t); 4090 4143 \end{prototype} 4091 4144 … … 4247 4300 bool psMinimizeLMChi2(psMinimization *min, 4248 4301 psImage *covar, 4249 4302 psVector *params, 4250 4303 const psVector *paramMask, 4251 4252 4304 const psArray *x, 4305 const psVector *y, 4253 4306 const psVector *yErr, 4254 4307 psMinimizeLMChi2Func func); 4255 4308 \end{prototype} 4256 4309 … … 4287 4340 identical. 4288 4341 4289 \code{paramMask} must be of type \code{ps U8}, while \code{params} must4290 be of type \code{psF32}. The \code{func} function must be valid only 4291 for types \code{psF32}, \code{psF64}.4342 \code{paramMask} must be of type \code{psMask}, while \code{params} 4343 must be of type \code{psF32}. The \code{func} function must be valid 4344 only for types \code{psF32}, \code{psF64}. 4292 4345 4293 4346 \begin{prototype} … … 4396 4449 \begin{prototype} 4397 4450 psPolynomial1D *psVectorFitPolynomial1D(psPolynomial1D *poly, 4398 4399 unsigned intmaskValue4400 4451 const psVector *mask, 4452 psMask maskValue 4453 const psVector *f, 4401 4454 const psVector *fErr 4402 4455 const psVector *x); 4403 4456 psPolynomial2D *psVectorFitPolynomial2D(psPolynomial1D *poly, 4404 4405 unsigned intmaskValue4406 4457 const psVector *mask, 4458 psMask maskValue 4459 const psVector *f, 4407 4460 const psVector *fErr 4408 4461 const psVector *x, 4409 4462 const psVector *y); 4410 4463 psPolynomial3D *psVectorFitPolynomial3D(psPolynomial1D *poly, 4411 4412 unsigned intmaskValue4413 4464 const psVector *mask, 4465 psMask maskValue 4466 const psVector *f, 4414 4467 const psVector *fErr 4415 4468 const psVector *x, … … 4417 4470 const psVector *z); 4418 4471 psPolynomial4D *psVectorFitPolynomial4D(psPolynomial1D *poly, 4419 4420 unsigned intmaskValue4421 4472 const psVector *mask, 4473 psMask maskValue 4474 const psVector *f, 4422 4475 const psVector *fErr 4423 4476 const psVector *x, … … 4442 4495 \begin{prototype} 4443 4496 psPolynomial1D *psVectorClipFitPolynomial1D(psPolynomial1D *poly, 4444 psStats*stats,4445 const psVector*mask,4446 unsigned intmaskValue4447 const psVector*f,4448 const psVector 4449 const psVector 4497 psStats *stats, 4498 const psVector *mask, 4499 psMask maskValue 4500 const psVector *f, 4501 const psVector *fErr 4502 const psVector *x); 4450 4503 psPolynomial2D *psVectorClipFitPolynomial2D(psPolynomial1D *poly, 4451 psStats*stats,4452 const psVector*mask,4453 unsigned intmaskValue4454 const psVector*f,4455 const psVector 4456 const psVector 4457 const psVector 4504 psStats *stats, 4505 const psVector *mask, 4506 psMask maskValue 4507 const psVector *f, 4508 const psVector *fErr 4509 const psVector *x, 4510 const psVector *y); 4458 4511 psPolynomial3D *psVectorClipFitPolynomial3D(psPolynomial1D *poly, 4459 psStats*stats,4460 const psVector*mask,4461 unsigned intmaskValue4462 const psVector*f,4463 const psVector 4464 const psVector 4465 const psVector 4466 const psVector 4512 psStats *stats, 4513 const psVector *mask, 4514 psMask maskValue 4515 const psVector *f, 4516 const psVector *fErr 4517 const psVector *x, 4518 const psVector *y, 4519 const psVector *z); 4467 4520 psPolynomial4D *psVectorClipFitPolynomial4D(psPolynomial1D *poly, 4468 psStats*stats,4469 const psVector*mask,4470 unsigned intmaskValue4471 const psVector*f,4472 const psVector 4473 const psVector 4474 const psVector 4475 const psVector 4476 const psVector 4521 psStats *stats, 4522 const psVector *mask, 4523 psMask maskValue 4524 const psVector *f, 4525 const psVector *fErr 4526 const psVector *x, 4527 const psVector *y, 4528 const psVector *z, 4529 const psVector *t); 4477 4530 \end{prototype} 4478 4531 These functions replicate the capability of the vector fitting … … 4575 4628 const psImage *input, 4576 4629 const psImage *mask, 4577 unsigned intmaskVal,4630 psMask maskVal, 4578 4631 psRegion region, 4579 4632 psImageCutDirection direction, … … 4610 4663 const psImage *input, 4611 4664 const psImage *mask, 4612 unsigned intmaskVal,4665 psMask maskVal, 4613 4666 psRegion region, 4614 4667 unsigned int nSamples, … … 4630 4683 const psImage *input, 4631 4684 const psImage *mask, 4632 unsigned intmaskVal,4685 psMask maskVal, 4633 4686 float x, 4634 4687 float y, … … 4681 4734 psImage *psImageRebin(psImage *out, const psImage *in, 4682 4735 const psImage *mask, 4683 unsigned intmaskVal,4736 psMask maskVal, 4684 4737 int scale, const psStats *stats); 4685 4738 \end{prototype} … … 4755 4808 const psImage *input, 4756 4809 const psImage *inputMask, 4757 intinputMaskVal,4810 psMask inputMaskVal, 4758 4811 const psPlaneTransform *outToIn, 4759 4812 psRegion region, … … 4771 4824 If the \code{inputMask} is non-\code{NULL}, those pixels in the 4772 4825 \code{inputMask} matching \code{inputMaskVal} are to be ignored in the 4773 transformation. The \code{inputMask} must be of type \code{ps U8}, and4826 transformation. The \code{inputMask} must be of type \code{psMask}, and 4774 4827 of the same size as the \code{input}, otherwise the function shall 4775 4828 generate an error and return \code{NULL}. The transformation … … 4797 4850 const psImage *in, 4798 4851 const psImage *mask, 4799 unsigned intmaskVal);4852 psMask maskVal); 4800 4853 \end{prototype} 4801 4854 Determine statistics for image (or subimage). The statistics to be … … 4810 4863 const psImage *in, 4811 4864 const psImage *mask, 4812 unsigned intmaskVal);4865 psMask maskVal); 4813 4866 \end{prototype} 4814 4867 Construct a histogram from an image (or subimage). The histogram to … … 4838 4891 \begin{prototype} 4839 4892 complex double psImagePixelInterpolate(const psImage *input, float x, float y, 4840 const psImage *mask, unsigned intmaskVal,4893 const psImage *mask, psMask maskVal, 4841 4894 complex double unexposedValue, psImageInterpolateMode mode); 4842 4895 \end{prototype} … … 4921 4974 4922 4975 \begin{prototype} 4923 psImage *psImageGrowMask(psImage *out, const psImage *in, unsigned intmaskVal,4924 unsigned int growSize, unsigned int growValue);4976 psImage *psImageGrowMask(psImage *out, const psImage *in, psU16 maskVal, 4977 unsigned int growSize, psU16 growVal); 4925 4978 \end{prototype} 4926 4979 … … 4935 4988 \code{maskVal} shall have the corresponding pixel in the \code{out} 4936 4989 image set to the \code{growValue}. The function must be defined for 4937 the following types: \code{psU8}, \code{psU16}. 4938 4939 \begin{prototype} 4940 psImage *psPixelsToMask(psImage *out, const psPixels *pixels, psRegion region, unsigned int maskVal); 4941 psPixels *psPixelsFromMask(psPixels *out, const psImage *mask, unsigned int maskVal); 4942 \end{prototype} 4943 4944 \code{psPixelsToMask} shall return an image of type U8 with the 4945 \code{pixels} lying within the specified \code{region} set to the 4990 the following types: \code{psU8}, \code{psU16}. Note that 4991 \code{maskVal} and \code{growVal} are not of type \code{psMask}, but 4992 \code{psU16} so that they match the maximum required type for the 4993 \code{in} image. 4994 4995 \begin{prototype} 4996 psImage *psPixelsToMask(psImage *out, const psPixels *pixels, psRegion region, psMask maskVal); 4997 psPixels *psPixelsFromMask(psPixels *out, const psImage *mask, psMask maskVal); 4998 \end{prototype} 4999 5000 \code{psPixelsToMask} shall return an image of type \code{psMask} with 5001 the \code{pixels} lying within the specified \code{region} set to the 4946 5002 \code{maskVal}. The \code{out} image shall be modified if supplied, 4947 5003 or allocated and returned if \code{NULL}. The size of the output
Note:
See TracChangeset
for help on using the changeset viewer.
