08-compiler-features.tex

\chapter{Compiler Features}
\label{cr-features}
\state{NoContent}

\section{Dead Code Elimination}
\label{cr-dce}

Dead Code Elimination, or \emph{DCE}, is a compiler feature which removes unused code from the output. After typing, the compiler evaluates the DCE entry-points (usually the main-method) and recursively determines which fields and types are used. Used fields are marked accordingly and unmarked fields are then removed from their classes.

DCE has three modes which are set when invoking the command line:

\begin{description}
	\item[-dce std:] Only classes in the Haxe Standard Library are affected by DCE. This is the default setting on all targets but \target{Javascript}.
	\item[-dce no:] No DCE is performed.
	\item[-dce full:] All classes are affected by DCE. This is the default setting when targeting \target{Javascript}.
\end{description}
The DCE-algorithm works well with typed code, but may fail when \tref{dynamic}{types-dynamic} or \tref{reflection}{std-reflection} is involved. This may require explicit marking of fields or classes as being used by attributing the following metadata:

\begin{description}
	\item[\expr{@:keep}:] If used on a class, the class along with all fields is unaffected by DCE. If used on a field, that field is unaffected by DCE.
	\item[\expr{@:keepSub}:] If used on a class, it works like \expr{@:keep} on the annotated class as well as all subclasses.
	\item[\expr{@:keepInit}:] Usually, a class which had all fields removed by DCE (or is empty to begin with) is removed from the output. By using this metadata, empty classes are kept.
\end{description}

If a class needs to be marked with \expr{@:keep} from the command line instead of editing its source code, there is a compiler macro available for doing so: \expr{--macro keep('type dot path')} See the \href{http://api.haxe.org/haxe/macro/Compiler.html#keep}{haxe.macro.Compiler.keep API} for details of this macro. It will mark package, module or sub-type to be kept by DCE and includes them for compilation.
 
The compiler automatically defines the flag \expr{dce} with a value of either \expr{"std"}, \expr{"no"} or \expr{"full"} depending on the active mode. This can be used in \tref{conditional compilation}{lf-condition-compilation}.

\trivia{DCE-rewrite}{DCE was originally implemented in Haxe 2.07. This implementation considered a function to be used when it was explicitly typed. The problem with that was that several features, most importantly interfaces, would cause all class fields to be typed in order to verify type-safety. This effectively subverted DCE completely, prompting the rewrite for Haxe 2.10.}

\trivia{DCE and try.haxe.org}{DCE for the \type{Javascript} target saw vast improvements when the website \url{http://try.haxe.org} was published. Initial reception of the generated \target{Javascript} code was mixed, leading to a more fine-grained selection of which code to eliminate.}

\section{Completion}
\label{cr-completion}

\subsection{Field Access}
\label{cr-completion-field-access}

\subsection{Call Arguments}
\label{cr-completion-call-arguments}

\subsection{Usage}
\label{cr-completion-usage}

\subsection{Position}
\label{cr-completion-position}

\subsection{Toplevel}
\label{cr-completion-toplevel}

\section{Resources}
\label{cr-resources}
\flag{fold}{true}

Haxe provides a simple resource embedding system that can be used for embedding files directly into the compiled application.

While it may be not optimal to embed large assets such as images or music in the application file, it comes in very handy for embedding smaller resources like configuration or XML data.

\subsection{Embedding resources}
\label{cr-resources-embed}

External files are embedded using the \emph{-resource} compiler argument:

\todo{what to use for listing of non-haxe code like hxml?}
\begin{lstlisting}
-resource hello_message.txt@welcome
\end{lstlisting}

The string after the \emph{@} symbol is the \emph{resource identifier} which is used in the code for retrieving the resource. If it is omitted (together with the \emph{@} symbol) then the file name will become the resource identifier.

\subsection{Retrieving text resources}
\label{cr-resources-getString}

To retrieve the content of an embedded resource we use the static method \emph{getString} of \type{haxe.Resource}, passing a \emph{resource identifier} to it:

\haxe{assets/ResourceGetString.hx}

The code above will display the content of the \emph{hello_message.txt} file that we included earlier using \emph{welcome} as the identifier.

\subsection{Retrieving binary resources}
\label{cr-resources-getBytes}

While it's not recommended to embed large binary files in the application, it still may be useful to embed binary data. The binary representation of an embedded resource can be accessed using the static method \emph{getBytes} of \type{haxe.Resource}:

\haxe{assets/ResourceGetBytes.hx}

The return type of \emph{getBytes} method is \type{haxe.io.Bytes}, which is an object providing access to individual bytes of the data.

\subsection{Implementation details}
\label{cr-resources-impl}

Haxe uses the target platform's native resource embedding if there is one, otherwise it provides its own implementation.

\begin{itemize}
\item \emph{Flash} resources are embedded as ByteArray definitions
\item \emph{C\#} resources are included in the compiled assembly
\item \emph{Java} resources are packed in the resulting JAR file
\item \emph{C++} resources are stored in global byte array constants.
\item \emph{JavaScript} resources are serialized in Haxe serialization format and stored in a static field of \type{haxe.Resource} class.
\item \emph{Neko} resources are stored as strings in a static field of \type{haxe.Resource} class.
\end{itemize}



\section{Runtime Type Information}
\label{cr-rtti}

The Haxe compiler generates runtime type information (RTTI) for classes that are annotated or extend classes that are annotated with the \expr{:rtti} metadata. This information is stored as a XML string in a static field \expr{__rtti} and can be processed through \type{haxe.rtti.XmlParser}. The resulting structure is described in \Fullref{cr-rtti-structure}.

\since{3.2.0}

The type \type{haxe.rtti.Rtti} has been introduced in order to simplify working with RTTI. Retrieving this information is now very easy:

\haxe{assets/RttiUsage.hx}

\subsection{RTTI structure}
\label{cr-rtti-structure}

\paragraph{General type information}

\begin{description}
	\item[path:] The \tref{type path}{define-type-path} of the type.
	\item[module:] The type path of the \tref{module}{define-module} containing the type.
	\item[file:] The full slash path of the .hx file containing the type. This might be \expr{null} in case there is no such file, e.g. if the type is defined through a \tref{macro}{macro}.
	\item[params:] An array of strings representing the names of the \tref{type parameters}{type-system-type-parameters} the type has. As of Haxe 3.2.0, this does not include the \tref{constraints}{type-system-type-parameter-constraints}.
	\item[doc:] The documentation of the type. This information is only available if the \tref{compiler flag}{define-compiler-flag} \expr{-D use_rtti_doc} was in place. Otherwise, or if the type has no documentation, the value is \expr{null}.
	\item[isPrivate:] Whether or not the type is \tref{private}{define-private-type}.
	\item[platforms:] A list of strings representing the targets where the type is available.
	\item[meta:] The meta data the type was annotated with.
\end{description}
	
\paragraph{Class type information}
\label{cr-rtti-class-type-information}

\begin{description}
	\item[isExtern:] Whether or not the class is \tref{extern}{lf-externs}.
	\item[isInterface:] Whether or not the class is actually an \tref{interface}{types-interfaces}.
	\item[superClass:] The class' parent class defined by its type path and list of type parameters.
	\item[interfaces:] The list of interfaces defined by their type path and list of type parameters.
	\item[fields:] The list of member \tref{class fields}{class-field}, described in \Fullref{cr-rtti-class-field-information}.
	\item[statics:] The list of static class fields, described in \Fullref{cr-rtti-class-field-information}.
	\item[tdynamic:] The type which is \tref{dynamically implemented}{types-dynamic-implemented} by the class, or \expr{null} if no such type exists.
\end{description}

\paragraph{Enum type information}

\begin{description}
	\item[isExtern:] Whether or not the enum is \tref{extern}{lf-externs}.
	\item[constructors:] The list of enum constructors.
\end{description}

\paragraph{Abstract type information}

\begin{description}
	\item[to:] An array containing the defined \tref{implicit to casts}{types-abstract-implicit-casts}.
	\item[from:] An array containing the defined \tref{implicit from casts}{types-abstract-implicit-casts}.
	\item[impl:] The \tref{class type information}{cr-rtti-class-type-information} of the implementing class.
	\item[athis:] The \tref{underlying type}{define-underlying-type} of the abstract.
\end{description}
	
	
\paragraph{Class field information}
\label{cr-rtti-class-field-information}

\begin{description}
	\item[name:] The name of the field.
	\item[type:] The type of the field.
	\item[isPublic:] Whether or not the field is \tref{public}{class-field-visibility}.
	\item[isOverride:] Whether or not the field \tref{overrides}{class-field-override} another field.
	\item[doc:] The documentation of the field. This information is only available if the \tref{compiler flag}{define-compiler-flag} \expr{-D use_rtti_doc} was in place. Otherwise, or if the field has no documentation, the value is \expr{null}.
	\item[get:] The \tref{read access behavior}{define-read-access} of the field.
	\item[set:] The \tref{write access behavior}{define-write-access} of the field.
	\item[params:] \item[params:] An array of strings representing the names of the \tref{type parameters}{type-system-type-parameters} the field has. As of Haxe 3.2.0, this does not include the \tref{constraints}{type-system-type-parameter-constraints}.
	\item[platforms:] A list of strings representing the targets where the field is available.
	\item[meta:] The meta data the field was annotated with.
	\item[line:] The line number where the field is defined. This information is only available if the field has an expression. Otherwise the value is \expr{null}.
	\item[overloads:] The list of available overloads for the fields, or \expr{null} if no overloads exists.
\end{description}

\paragraph{Enum constructor information}
\label{cr-rtti-enum-constructor-information}

\begin{description}
	\item[name:] The name of the constructor.
	\item[args:] The list of arguments the constructor has, or \expr{null} if no arguments are available.
	\item[doc:] The documentation of the constructor. This information is only available if the \tref{compiler flag}{define-compiler-flag} \expr{-D use_rtti_doc} was in place. Otherwise, or if the constructor has no documentation, the value is \expr{null}.
	\item[platforms:] A list of strings representing the targets where the constructor is available.
	\item[meta:] The meta data the constructor was annotated with.
\end{description}