Changeset 397

Timestamp:

Apr 7, 2004, 4:13:17 PM (22 years ago)

Author:

Paul Price

Message:

Small changes to psDlist explanation.
Added section in memory management about what psMyTypeAlloc
and psMyTypeFree should do. This is important to define because
of the metadata, but it probably needs some more thought.

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (9 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.32 2004-04-07 03:26:07 eugene Exp $
+%%% $Id: psLibSDRS.tex,v 1.33 2004-04-08 02:13:17 price Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -487 +487 @@
 
 \tbd{REF}.
+
+\subsubsection{Relation of Memory Management to Structures}
+
+In this document, we specify several C \code{struct}s.  It is expected
+that instances of, for example, \code{struct psMyType} will be
+constructed using \code{psMyTypeAlloc()} calls, and destructed using
+\code{psMyTypeFree()} calls.  The allocator will allocate the required
+memory with \code{psAlloc} and increment the appropriate
+\code{refCounter}.  The destructor will decrement the appropriate
+\code{refCounter} and free the memory with \code{psFree} \emph{if and
+only if} the new value of the \code{refCounter} is zero.
+
+This allows the \code{psMyType} to be imported into the metadata
+(\S\ref{sec:metadata}) without the user worrying about the details of
+the memory allocation/deallocation.  For example:
+
+\begin{verbatim}
+void psFooMetadata(psMetadata *md)
+{
+    psFoo *foo = psFooAlloc();
+    (void) psMetaDataAppend(md, psMetaDataItemAlloc(PS_META_FOO,foo,"Comment","foo.bar"));
+    (void) psFooFree(foo);
+}
+\end{verbatim}
+
+In the above case, \code{foo} is created, stuffed into the metadata,
+and then the programmer follows the rule of ``for every \code{alloc},
+there is an equal and opposite free'' before the function returns.
+However, the metadata needs to carry around the \code{psFoo}, and so
+it is important that \code{psFooFree} does not free the memory for
+\code{foo}, but only decrements its \code{refCounter}.  Hence, at the
+conclusion of the function, the memory pointed to by \code{foo} in the
+course of the function remains allocated, and the corresponding
+\code{refCounter} is 1 (specifically, the reference in the metadata).
 
 \subsection{Tracing and Logging}
@@ -1016 +1050 @@
 \code{psDlist} may have changed.  The value of \code{where} specifies
 if the specified data item should be placed on the front of the list
-(\code{PS_DLIST_HEAD}), or at the end of the list
-(\code{PS_DLIST_TAIL}).
+(\code{PS_DLIST_HEAD}), at the end of the list (\code{PS_DLIST_TAIL}),
+to add after (\code{PS_DLIST_NEXT}) or before (\code{PS_DLIST_PREV})
+the current element (specified by the iteration cursor), or an index
+that the new \code{data} should inhabit.
 
 A data item may be retrieved from the list with the function:
@@ -2329 +2365 @@
 
 \subsection{Metadata}
+\label{sec:metadata}
 
 \subsubsection{Conceptual Overview}
@@ -2397 +2434 @@
 manipulation of the data should be reflected in the metadata where
 appropriate.  This is always an issue of concern.  For example,
-consider an image of dimensions \code{Nx, Ny}.  If a function extracts
-a subraster, it must change the values of \code{Nx, Ny} to match the
+consider an image of dimensions \code{nX, nY}.  If a function extracts
+a subraster, it must change the values of \code{nX, nY} to match the
 new dimensions.  What should it do to the corresponding metadata?
 Clearly, it should change the corresponding value which defines
-\code{Nx, Ny}.  However, it is not quite so simple: there may be other
+\code{nX, nY}.  However, it is not quite so simple: there may be other
 metadata values which depend on those values.  These must also be
 changed appropriately.  What if the metadata element points to a
@@ -2414 +2451 @@
 image exposure time is a notorious example in astronomy.  Different
 observatories use different header keywords (ie, metadata names) for
-the same concept of the exposure time (EXPTIME, EXPOSURE, OPENTIME,
-INTTIME, etc).  Any system which operates on these metadata needs to
-address the issue of identifying these names.  This issue seems like an
-argument for hardwiring metadata in the structure, but in fact it does
-not present such a strong case.  If the metadata are hardwired, some
-function will still have to know how to interpret the various names to
-populate the structure.  The concept can still be localized with
-generic metadata containers by including abstract metadata names
-within the code which are tied to the various implementations-specific
-metadata names.  
+the same concept of the exposure time (\code{EXPTIME},
+\code{EXPOSURE}, \code{OPENTIME}, \code{INTTIME}, etc).  Any system
+which operates on these metadata needs to address the issue of
+identifying these names.  This issue seems like an argument for
+hardwiring metadata in the structure, but in fact it does not present
+such a strong case.  If the metadata are hardwired, some function will
+still have to know how to interpret the various names to populate the
+structure.  The concept can still be localized with generic metadata
+containers by including abstract metadata names within the code which
+are tied to the various implementations-specific metadata names.
 
 \subsubsection{Metadata Representation}
@@ -2510 +2547 @@
 \end{verbatim}
 
-The type \code{psMetaDataSet} is a container class for metadata. Note that there are
-in fact \emph{two} representations of the metadata (each \code{psMetaDataItem} appears
-on both).
-
-We are using the standard \PS{} doubly-linked list types
-\code{psDlist} and \code{psHash}.  For example:
+The type \code{psMetaDataSet} is a container class for metadata. Note
+that there are in fact \emph{two} representations of the metadata
+(each \code{psMetaDataItem} appears on both).  The first
+representation employs a doubly-linked list that allows the order of
+the metadata to be preserved (e.g., if FITS headers are read in a
+particular order, they should be written in the same order).  The
+second representation employs a hash table which allows fast look-up
+given a specific metadata keyword.
+
+When we refer to ``metadata'' (especially in the case of images), we
+generally mean a \code{psMetaDataSet}:
+\begin{verbatim}
+typedef psMetaDataSet psMetadata;
+\end{verbatim}
+
+An example of the usage of the metadata APIs is as follows:
 \begin{verbatim}
     for (int i = 0; i < 10; i += 5) {
@@ -2574 +2621 @@
 \end{verbatim}
 
-It is an unfortunate fact that certain metadata keywords (such as \code{COMMENT} in a FITS header)
-may be repeated with different values.  The \code{psMetaDataAppend} routine is required
-to check that all metadata names are unique unless the type is qualified as \code{PS_META_NON_UNIQUE};
-in this case a unique integer will be added to each name that you specify. In this case,
-you may either delete individual element separately or as a complete set:
+It is an unfortunate fact that certain metadata keywords (such as
+\code{COMMENT} and \code{HISTORY} in a FITS header) may be repeated
+with different values.  The \code{psMetaDataAppend} routine is
+required to check that all metadata names are unique unless the type
+is qualified as \code{PS_META_NON_UNIQUE}; in this case a unique
+integer will be added to each name that you specify. In this case, you
+may either delete individual element separately or as a complete set:
 \begin{verbatim}
 psMetaDataItemFree(psMetaDataRemove(ms, "lang.hello.0"));
@@ -2585 +2634 @@
 
 \subsubsection{MetaData APIs}
+
+In this section, we explain the metadata APIs more fully.
+
+The allocator for \code{psMetaDataItem} returns a full
+\code{psMetaDataItem} ready for insertion into the
+\code{psMetaDataSet}.  It is important to note that, in order to
+support multiple types, the data being input must be a pointer, even
+if it is a \code{float} or \code{int}, for example.  The name of the
+\code{psMetaDataItem} takes a \code{sprintf} format string, with the
+corresponding arguments following.
+
+Note that the destructor does not 
 
 \begin{verbatim}