%%%% -*- Mode: LaTeX -*-
%%%% CL-PQs.tex --
\documentclass{article}
\usepackage{latexsym}
\usepackage{epsfig}
\usepackage{alltt}
\usepackage{titlesec}
\newcommand{\tm}{$^\mathsf{tm}$}
\newcommand{\cfr}{\emph{cfr.}}
\newcommand{\Lisp}{\textsf{Lisp}}
\newcommand{\CL}{\textsf{Common~Lisp}}
\newcommand{\Java}{\textsc{Java}}
\newcommand{\checkcite}[1]{{\textbf{[Missing Citation: #1]}}}
\newcommand{\checkref}[1]{{\textbf{[Missing Reference: #1]}}}
\newcommand{\missingpart}[1]{{\ }\vspace{2mm}\\
{\textbf{[Still Missing: #1]}}\\
\vspace{2mm}}
\newcommand{\marginnote}[1]{%
\marginpar{\raggedright \begin{small}\begin{em}#1
\end{em}\end{small}}}
%\addtolength{\textwidth}{2cm}
%%% CL
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\term}[1]{\texttt{#1}}
\newcommand{\nonterm}[1]{\textit{$$}}
\newcommand{\kwd}[1]{\texttt{:#1}}
\newcommand{\variable}[1]{\textit{#1}}
\newcommand{\clglossary}[1]{\emph{#1}}
\newcommand{\CPL}{\subsubsection*{Class Precedence List:}}
\newcommand{\Syntax}{\subsubsection*{Syntax:}}
\newcommand{\ArgsValues}{\subsubsection*{Arguments and Values:}}
\newcommand{\Description}{\subsubsection*{Description:}}
\newcommand{\Examples}{\subsubsection*{Examples:}}
\newcommand{\AffectedBy}{\subsubsection*{Affected by:}}
\newcommand{\Exceptions}{\subsubsection*{Exceptional Situations:}}
\newcommand{\SeeAlso}{\subsubsection*{See Also:}}
\newcommand{\Notes}{\subsubsection*{Notes:}}
%%% Document specific macros.
\newcommand{\heap}{\texttt{heap}}
\newcommand{\heapfinger}{\texttt{heap-finger}}
\title{\LARGE \bfseries Priority Queues for \CL{}}
\author{Ingvar Mattsson\\\texttt{}\\[2mm]Marco Antoniotti\\\texttt{}}
\begin{document}
\maketitle
\paragraph{Keywords:} Heap, Priority Queue, \CL{}.
\section{Introduction}
This is a specification for the intruduction of a common API for
\emph{priority queues}, also called \emph{heaps}, in \CL{}. The
specification tries to take into account the common elements present
in the several implementations available on the Internet, and to
ensure that the API is generic enough to allow for the seamless
inclusion of particular flavors of heaps. An inspiration for this
specification API is \cite{CLRS}, especially w.r.t., the discussion
about \textsc{Heaps} and \textsc{Fibonacci Heaps}.
\subsection{Rationale}
There is no standard \emph{heap} (or \emph{priority queue}) implementation
in the Common Lisp standard. It is, however, a useful data structure.
The intention of this document is to provide a portable, flexible,
heap API that can be used on essentially all data where storing
according to a ranking criterion makes sense.
This API specification carefully does not discuss how it behaves in a
multi-processing environment.
\subsection{Guarantees}
\subsubsection{Time complexity}
The heap data structure gives you $O(1)$ peek at one extreme of the
heap. It also gives you $O(\lg n)$ addition and removal from the heap.
However, the $O(\lg n)$ insertion and removal relies on an $O(1)$
comparison operator. With having user-specified comparison (and key
extraction) operators, the best guarantee the reference implementation
can give is that insertion and removal is $O(C \lg n)$ for a
comparator complexity of $O(C)$.
\subsubsection{Multi-processing}
There are no explicit multi-processing or concurrency guarantees for
the generic heaps. However, implementors are encouraged to add
recursive locks to each heap object and lock/unlock these as
necessary.
\subsubsection{Side-effects}
Any code that modifies an object currently present in a heap is likely to
breach the heap invariant. Doing that is highly discouraged. However,
modifying things within an object that does not, in any way,
contribute to the value used in comparisons may be safe.
\subsection{Design Choices}
There are a few design choices to be made when specifying an API for
\emph{heaps}. The following is a list of foreseen issues and their
tratment.
\subsubsection{Heap Test must be a Total Order}
There is no way for a \CL{} implementation to check and ensure that
the function that becomes the \emph{heap test} (cfr., the constuctor
\code{make-heap}) is a \emph{total order} (modulo equality).
Providing a function that does not represent a total order has
\emph{undefined consequences}.
\subsubsection{Equal Keys}
The relative order to elements in a heap that admits \emph{equal
keys} is \emph{implementation dependent} and should not be relied
upon.
\titleformat{\subsection}{%
\titlerule
\vspace{1mm}}{\large\bfseries\thesubsection}{1em}{\large\bfseries\sffamily}
\section{Heaps Dictionary}
% \subsection{Package}
% All symbols of a generic heap implementation should be accessible in
% a package names such that :genheap is a designator for the
% package.
% This means that only one GENHEAP implementation can be loaded in any
% given image, without having to do package renaming. However, it makes
% it easier for developers to write code against the package or probe
% for the package's existence using FIND-PACKAGE.
% The functional interface presented is a minimum interface, it may be
% that an implementor is willing to give guarantees for the
% implementation that extend beyond this.
% The exact underlying data structures are not specified. The reference
% implementations use CLOS, generic functions and methods on these for
% its implementation. One of them defines new methods as new generic
% heap types are asked for, the other one doesn't.
\subsection{Class \heap{}}
\CPL{}
\heap{}, \ldots, \code{T}
\Description{}
Any implementation of this specification will provide a \emph{class}
named \heap{}.
\Notes{}
Each implementation is given the liberty to choose
whether to use a\\\code{structure-class} or a \code{standard-class} (or
another full-blown CLOS class)\marginnote{This implies that specialized
heaps can only be derived via single inheritance.}.
\subsection{Generic Function \code{heap-p}}
\Syntax{}
\code{heap-p} \variable{object} $\Rightarrow$ \variable{generalized-boolean}
\ArgsValues{}
\begin{description}
\item[\variable{object} --] an \clglossary{object}.
\item[\variable{generalized-boolean} --] a \clglossary{generalized boolean}.
\end{description}
\Description{}
This function returns \code{NIL} when called on a non-heap
\variable{object} and a non-null value if presented with a heap
\variable{object}.
\subsection{Slot Readers \code{heap-size}, \code{heap-total-size},\\
\code{heap-key-function}, \code{heap-test-function}}
\Syntax{}
\code{heap-size} \variable{heap} $\Rightarrow$ \variable{size}
\noindent
\code{heap-total-size} \variable{heap} $\Rightarrow$ \variable{total-size}
\noindent
\code{heap-key-function} \variable{heap} $\Rightarrow$
\variable{keyfun}
\noindent
\code{heap-test-function} \variable{heap} $\Rightarrow$
\variable{cmpfun}
\ArgsValues{}
\begin{description}
\item[\variable{heap} --] a \heap{}.
\item[\variable{heap-key-function} --] a \clglossary{function designator}.
\item[\variable{heap-test-function} --] a \clglossary{function designator}.
\item[\variable{size} --] a (positive) integer\marginnote{Maybe be more precise}.
\item[\variable{total-size} --] a (positive) integer\marginnote{Maybe be more precise}.
\end{description}
\Description{}
The \code{heap-size} and \code{heap-total-size} return the number of
elements in the \variable{heap}
The \code{heap-key-function} and \code{heap-test-function} accessors
return the \emph{test} function and the \emph{key} function used by
the \variable{heap} implementation to maintain the heap invariant.
\subsection{Type \heapfinger{}}
Many operations on heaps require to ``change'' something that is
located in a certain ``position'' in the underlying data structure.
To support these operations the specification requires implementations
to provide an opaque type named \heapfinger{}, i.e., to provide a way
to keep a ``finger'' on a certain position within the
heap\footnote{The term ``finger'' has been extensively used in the
algorithms and data structure literature.}.
As an example, a traditional implementation of heaps based on arrays
could define \heapfinger{} as
\begin{alltt}
(deftype \heapfinger{} () 'fixnum)
\end{alltt}
\Notes{}
This specification does not prescribe anything in particular regarding
the behavior of \heapfinger{}s and the garbage collector. An
implementation is free to add a \code{:weak} key to the \code{make-heap}
constructor (see below) and to return a \emph{weak} \heapfinger{},
that works well with the garbage collector.
\subsection{Function \code{heap-finger-p}}
\Syntax{}
\code{heap-finger-p} \variable{object} $\Rightarrow$
\variable{boolean}
\ArgsValues{}
\begin{description}
\item [\variable{object} --] an \clglossary{object}.
\item [\variable{boolean} --] a \code{boolean}.
\end{description}
\Description{}
Returns \code{T} if \variable{object} is a \heapfinger{}, \code{NIL}
otherwise.
\subsection{Condition \code{heap-error}}
\CPL{}
\code{heap-error}, \code{simple-error}, \ldots, \code{T}
\Description{}
The root of specialized errors raised by the heap operations; the heap
for which the error is being signaled can be initialized with the
keyword \code{:heap} and can be read by the accessor
\code{heap-error-heap}. The default for the underlying slot is \code{NIL}.
\SeeAlso{}
\code{heap-error-heap}.
\subsection{Function \code{heap-error-heap}}
\Syntax{}
\code{heap-error-heap} \variable{heap-error} $\Rightarrow$ \variable{heap}
\ArgsValues{}
\begin{description}
\item[\variable{heap-error} --] a \code{heap-error}
\item[\variable{heap} --] a \heap{}.
\end{description}
\Description{}
Returns the \variable{heap} associated to the condition
\variable{heap-error} or \code{NIL} if the slot is uninitialized.
\subsection{Condition \code{empty-heap-error}}
\CPL{}
\code{empty-heap-error}, \code{heap-error}, \ldots, \code{T}
\Description{}
The condition that may be signaled when certain operations are
attempted on an empty heap.
\SeeAlso{}
\code{heap-error-heap}, \code{heap-error}.
\subsection{Condition \code{invalid-heap-finger-error}}
\CPL{}
\code{invalid-heap-finger-error}, \code{heap-error},
\code{cell-error}, \ldots, \code{T}
\Description{}
The condition that may be signaled when certain operations are
attempted on an \emph{invalid} ``position'' in a heap. The offending
\emph{finger} must be passed at initialization time with the keyword
\kwd{name}.
\SeeAlso{}
\code{heap-error-heap}, \code{heap-error}, \heapfinger{}.
\Notes{}
\code{invalid-heap-finger-error} inherits from \code{cell-error},
hence, \code{cell-error-name} is used to get the offending \emph{finger}.
\subsection{Condition \code{invalid-key-error}}
\CPL{}
\code{invalid-key-error}, \code{heap-error}, \ldots, \code{T}
\Description{}
The condition that may be signaled when certain operations are
attempted with an \emph{invalid} ``key'' in a heap. The offending key
is initialized using the \kwd{offender} keyword and can be retrieved
by the \code{invalid-key-error-offender} function.
\SeeAlso{}
\code{invalid-key-error-offender},
\code{heap-error-heap}, \code{heap-error}.
\subsection{Function \code{invalid-key-error-offender}}
\Syntax{}
\code{invalid-key-error-offender} \variable{i-k-e} $\Rightarrow$
\variable{key-object}
\ArgsValues{}
\begin{description}
\item[\variable{i-k-e} --] a \code{invalid-key-error}.
\item[\variable{key-object} --] a \clglossary{object}.
\end{description}
\Description{}
Given an instance of \code{invalid-key-error},
\code{invalid-key-error-offender} returns the offending
\variable{key-object} associated with \variable{i-k-e}.
\subsection{Function \code{make-heap}}
\Syntax{}
\code{make-heap} \code{\&key} \variable{test} \variable{key}
\variable{initial-size} \variable{class} \variable{initial-contents}
\code{\&allow-other-keys}
$\Rightarrow$ \variable{heap}
\subsubsection*{Arguments and Values:}
\begin{description}
\item[\variable{test} --] a \clglossary{function designator} for a binary
function returning a \clglossary{generalized boolean}; default is
\verb|}.
\end{document}
%%%% end of file -- CL-PQs.tex --