% !TeX root = forth.tex
\chapter{The optional Memory-Allocation word set} % 14
\wordlist{memory}

\section{Introduction} % 14.1

\section{Additional terms and notation} % 14.2
None.

\section{Additional usage requirements} % 14.3

\setcounter{subsection}{2}
\subsection{Allocated regions (14.3.3)} % 14.3.3

A program may address memory in data space regions made available
by \word{ALLOCATE} or \word{RESIZE} and not yet released by \word{FREE}.

See: \xref[3.3.3 Data space]{usage:dataspace}.


\section{Additional documentation requirements} % 14.4
\label{mem:docs}

None.

\section{Compliance and labeling} % 14.5

\subsection{Forth-\snapshot{} systems} % 14.5.1

The phrase ``Providing the Memory-Allocation word set'' shall be
appended to the label of any Standard System that provides all of
the Memory-Allocation word set.

The phrase ``Providing \emph{name(s)} from the Memory-Allocation
Extensions word set'' shall be appended to the label of any Standard
System that provides portions of the Memory-Allocation Extensions
word set.

The phrase ``Providing the Memory-Allocation Extensions word set''
shall be appended to the label of any Standard System that provides
all of the Memory-Allocation and Memory-Allocation Extensions word
sets.

\subsection{Forth-\snapshot{} programs} % 14.5.2

The phrase ``Requiring the Memory-Allocation word set'' shall be
appended to the label of Standard Programs that require the system
to provide the Memory-Allocation word set.

The phrase ``Requiring \emph{name(s)} from the Memory-Allocation
Extensions word set'' shall be appended to the label of Standard
Programs that require the system to provide portions of the
Memory-Allocation Extensions word set.

The phrase ``Requiring the Memory-Allocation Extensions word set''
shall be appended to the label of Standard Programs that require
the system to provide all of the Memory-Allocation and
Memory-Al\-lo\-ca\-tion Extensions word sets.

\section{Glossary} % 14.6

\subsection{Memory-Allocation words} % 14.6.1

\vspace*{-1ex}
\begin{worddef}{0707}{ALLOCATE}
\item \stack{u}{a-addr ior}

	Allocate \param{u} address units of contiguous data space. The
	data-space pointer is unaffected by this operation. The initial
	content of the allocated space is undefined.

	If the allocation succeeds, \param{a-addr} is the aligned
	starting address of the allocated space and \param{ior} is
	zero.

	If the operation fails, \param{a-addr} does not represent a valid
	address and \param{ior} is the {im\-ple\-ment\-ation-de\-fin\-ed} I/O result
	code.

\see \wref{core:HERE}{HERE},
	\wref{memory:FREE}{FREE},
	\wref{memory:RESIZE}{RESIZE}.

	\begin{testing}
		\ttfamily
		\word{VARIABLE} datsp \\
		\word{HERE} datsp \word{!}

		\test{50 \word{CELLS} \word{ALLOCATE} \word{SWAP} addr \word{!}}{0} \\
		\test{addr \word{@} \word{ALIGNED}}{addr \word{@}}				\tab \word{bs} \textdf{Test address is aligned} \\
		\test{\word{HERE}}{datsp \word{@}}								\tab[5.9] \word{bs} \textdf{Check data space pointer is unaffected}\\
		addr \word{@} 50 write-cell-mem \\
		addr \word{@} 50 check-cell-mem \tab[3.5] \word{bs} \textdf{Check we can access the heap} \\
		\test{addr \word{@} \word{FREE}}{0}

		\test{99 \word{ALLOCATE} \word{SWAP} addr \word{!}}{0} \\
		\test{addr \word{@} \word{ALIGNED}}{addr \word{@}} \tab \word{bs} \textdf{Test address is aligned} \\
		\test{addr \word{@} \word{FREE}}{0} \\
		\test{\word{HERE}}{datsp \word{@}}								\tab[5.9] \word{bs} \textdf{Data space pointer unaffected by \word{FREE}}\\

		\test{-1 \word{ALLOCATE} \word{SWAP} \word{DROP} \word{0=}}{<FALSE>} \tab \word{bs} \textdf{Memory allocate failed}
	\end{testing}
\end{worddef}


\vspace*{-2ex}
\begin{worddef}{1605}{FREE}
\item \stack{a-addr}{ior}

	Return the contiguous region of data space indicated by
	\param{a-addr} to the system for later allocation. \param{a-addr}
	shall indicate a region of data space that was previously
	obtained by \word{ALLOCATE} or \word{RESIZE}. The data-space
	pointer is unaffected by this operation.

	If the operation succeeds, \param{ior} is zero. If the operation
	fails, \param{ior} is the implementation-defined I/O result code.

\see \wref{core:HERE}{HERE},
	\wref{memory:ALLOCATE}{ALLOCATE},
	\wref{memory:RESIZE}{RESIZE}.

	\begin{testing}
		\textdf{See \tref{memory:ALLOCATE}.}
	\end{testing}
\end{worddef}

\enlargethispage{6ex}
\begin{worddef}{2145}{RESIZE}
\item \stack{a-addr_1 u}{a-addr_2 ior}

	Change the allocation of the contiguous data space starting at
	the address \param{a-addr_1}, previously allocated by
	\word{ALLOCATE} or \word{RESIZE}, to \param{u} address units.
	\param{u} may be either larger or smaller than the current
	size of the region. The data-space pointer is unaffected by
	this operation.

	If the operation succeeds, \param{a-addr_2} is the aligned
	starting address of \param{u} address units of allocated memory
	and \param{ior} is zero. \param{a-addr_2} may be, but need
	not be, the same as \param{a-addr_1}. If they are not the same,
	the values contained in the region at \param{a-addr_1} are copied
	to \param{a-addr_2}, up to the minimum size of either of the
	two regions. If they are the same, the values contained in the
	region are preserved to the minimum of \param{u} or the original
	size.  If \param{a-addr_2} is not the same as \param{a-addr_1},
	the region of memory at \param{a-addr_1} is returned to the system
	according to the operation of \word{FREE}.

	If the operation fails, \param{a-addr_2} equals \param{a-addr_1},
	the region of memory at \param{a-addr_1} is unaffected, and
	\param{ior} is the implementation-defined I/O result code.

\see \wref{core:HERE}{HERE},
	\wref{memory:ALLOCATE}{ALLOCATE},
	\wref{memory:FREE}{FREE}.

	\begin{testing}\ttfamily
		\test{50 \word{CHARS} \word{ALLOCATE} \word{SWAP} addr \word{!}}{0} \\
		addr \word{@} 50 write-char-mem addr \word{@} 50 check-char-mem

		\word{bs} \textdf{Resize smaller does not change content.} \\
		\test{addr \word{@} 28 \word{CHARS} \word{RESIZE} \word{SWAP} addr \word{!}}{0} \\
		addr \word{@} 28 check-char-mem

		\word{bs} \textdf{Resize larger does not change original content.} \\
		\test{addr \word{@} 100 \word{CHARS} \word{RESIZE} \word{SWAP} addr \word{!}}{0} \\
		addr \word{@} 28 check-char-mem

		\word{bs} \textdf{Resize error does not change \param{addr}} \\
		\test{addr \word{@} -1 \word{RESIZE} \word{0=}}{addr \word{@} <FALSE>}

		\test{addr \word{@} \word{FREE}}{0} \\
		\test{\word{HERE}}{datsp \word{@}} \tab \word{bs} \textdf{Data space pointer is unaffected}
	\end{testing}
\end{worddef}

\vspace*{-2ex}
\subsection{Memory-Allocation extension words} % 14.6.2

None