\ignore{
\documentstyle[11pt]{report}
\textwidth 13.7cm
\textheight 21.5cm
\newcommand{\myimp}{\verb+ :- +}
\newcommand{\ignore}[1]{}
\def\definitionname{Definition}

\makeindex
\begin{document}
}

\chapter{The \texttt{sys} Module}\label{chapter:sys}
The \texttt{sys} module, which is imported by default, contains built-ins that are relevant to the Picat system.  The built-ins in the \texttt{sys} module perform operations that include compiling programs, tracing execution, and displaying statistics and information about the Picat system.   

\section{Compiling and Loading Programs}
The \texttt{sys} module includes a number of built-ins for compiling programs and loading them into memory.
\begin{itemize}
\item \texttt{compile($FileName$)}\index{\texttt{compile/1}}: This predicate compiles the file \texttt{$FileName$.pi} and all of its dependent files without loading the generated byte-code files.  The destination directory for the byte-code file is the same as the source file's directory.  If the Picat interpreter does not have permission to write into the directory in which a source file resides, then this built-in throws an exception. If \texttt{$FileName$.pi} imports modules, then these module files are also compiled. The system searches for these module files in the directory in which \texttt{$FileName$.pi} resides or the directories that are stored in the environment variable \texttt{PICATPATH}.

\item \texttt{compile\_bp($FileName$)}\index{\texttt{compile\_bp/1}}: This predicate translates the Picat file \texttt{$FileName$.pi} into a B-Prolog file \texttt{$FileName$.pl}.  If the file is dependent on other Picat files, then those files are compiled using \texttt{compile/1}\index{\texttt{compile/1}}.  The destination directory for the B-Prolog file is the same as the source file's directory.  If the Picat interpreter does not have permission to write into the directory in which a source file resides, then this built-in throws an exception.

\item \texttt{load($FileName$)}\index{\texttt{load/1}}: This predicate loads the byte-code file \texttt{$FileName$.qi} and all of its dependent byte-code files into the system for execution.  For $FileName$, the system searches for a byte-code file in the directory specified by $FileName$ or the directories that are stored in the environment variable \texttt{PICATPATH}. For the dependent file names, the system searches for a byte-code file in the directory in which \texttt{$FileName$.qi} resides or the directories that are stored in the environment variable \texttt{PICATPATH}. If the byte-code file \texttt{$FileName$.qi} does not exist, but the source file \texttt{$FileName$.pi} exists, then this built-in compiles the source file and loads the byte codes without creating a \texttt{qi} file.  Note that, for the dependent files, if the byte-code file does not exist, but the source file exists, then the source file will be compiled.

\item \texttt{cl($FileName$)}\index{\texttt{cl/1}}: This predicate compiles and loads the source file named \texttt{$FileName$.pi}.  Note that the extension \texttt{.pi} does not need to be given.  The system also compiles and loads all of the module files that are either directly imported or indirectly imported by the source file.  The system searches for such dependent files in the directory in which \texttt{$FileName$.pi} resides or the directories that are stored in the environment variable \texttt{PICATPATH}.  

\item \texttt{cl}\index{\texttt{cl/0}}: This predicate compiles and loads a program from the console, ending when the end-of-file character ({\tt ctrl-z} for Windows and {\tt ctrl-d} for Unix) is typed.

%For \texttt{$Filename$.pi} and each dependent module file, the compiler creates a byte-code file with the same main name and the extension name \texttt{.qi}.

\item \texttt{cl\_facts($Facts$)}\index{\texttt{cl\_facts/1}}: This predicate compiles and loads facts into the system.  The argument $Facts$ is a list of ground facts.

\item \texttt{cl\_facts($Facts$,$IndexInfo$)}\index{\texttt{cl\_facts/2}}: This predicate compiles and loads facts into the system.  The argument $Facts$ is a list of ground facts.  The argument $IndexInfo$ is a list of indexing information in the form \texttt{p($M_1$,$M_2$,\ldots,$M_n$)}.  Each $M_i$ can either be \texttt{+}, which indicates that the argument is input, or \texttt{-}, which indicates that the argument is output.

\item \texttt{cl\_facts\_table($Facts$)}\index{\texttt{cl\_facts\_table/1}}: This predicate is the same as \texttt{cl\_facts/1}, except that the facts are all tabled.

\item \texttt{cl\_facts\_table($Facts$,$IndexInfo$)}\index{\texttt{cl\_facts\_table/2}}: This predicate is the same as \texttt{cl\_facts/2}, except that the facts are all tabled.
\end{itemize}

\section{Tracing Execution}
The Picat system has three execution modes: \textit{non-trace mode}\index{non-trace mode}, \textit{trace mode}\index{trace mode}, and \textit{spy mode}\index{spy mode}.  In trace mode\index{trace mode}, it is possible to trace the execution of a program, showing every call in every possible stage.  In order to trace the execution, the program must be recompiled while the system is in trace mode\index{trace mode}.  In spy mode\index{spy mode}, it is possible to trace the execution of individual functions and predicates.  The following predicates are used to switch between non-trace mode\index{non-trace mode} and trace mode\index{trace mode}.
\begin{itemize}
\item \texttt{trace}\index{\texttt{trace/0}}: This predicate switches the execution mode to trace mode\index{trace mode}.
\item \texttt{notrace}\index{\texttt{notrace/0}}: This predicate switches the execution mode to non-trace mode\index{non-trace mode}.
\item \texttt{debug}\index{\texttt{debug/0}}: This predicate switches the execution mode to trace mode\index{trace mode}.
\item \texttt{nodebug}\index{\texttt{nodebug/0}}: This predicate switches the execution mode to non-trace mode\index{non-trace mode}.
\item \texttt{spy($Point$)}\index{\texttt{spy/1}}: This predicate places a spy point on $Point$, which is a function or a predicate, optionally followed by an arity.  The creation of a spy point switches the Picat system to spy mode\index{spy mode}.
\item \texttt{nospy}\index{\texttt{nospy/0}}: This predicate removes all spy points, and switches the execution mode to non-trace mode\index{non-trace mode}.
\item \texttt{abort}\index{\texttt{abort/0}}: This predicate terminates the current program.  This can be used in all three execution modes.
\end{itemize}

\subsection{Debugging Commands}
In trace mode\index{trace mode}, the system displays a message when a function or a predicate is entered (\texttt{Call}), exited (\texttt{Exit}), re-entered (\texttt{Redo}) or has failed (\texttt{Fail}).  After a function or a predicate is entered or re-entered, the system waits for a command from the user. A command is a single letter followed by a carriage-return, or may simply be a carriage-return. The following commands are available:  
\begin{itemize}
\item \texttt{+} : create a spy point.
\item \texttt{-} : remove a spy point.
\item \texttt{$<$} : reset the print depth to 10.
\item \texttt{$<$ i} : reset the print depth to \texttt{i}.
\item \texttt{a} : abort, quit debugging, moving control to the top level.
\item \texttt{<cr>} : A carriage return causes the system to show the next call trace. 
\item \texttt{c} :  creep, show the next call trace.
\item \texttt{h} : help, display the debugging commands.
\item \texttt{?} : help, display the debugging commands.
\item \texttt{l} :  leap, be silent until a spy point is encountered. 
\item \texttt{n} : nodebug, prevent the system from displaying debugging messages for the remainder of the program.
\item \texttt{r} : repeat, continue to creep or leap without intervention. 
\item \texttt{s} : skip, be silent until the call is completed (\texttt{Exit} or \texttt{Fail}). 
\item \texttt{t} : backtrace, show the backtrace leading to the current call.
\item \texttt{t i} : backtrace, show the backtrace from the call numbered \texttt{i} to the current call.
\item \texttt{u} : undo what has been done to the current call and redo it.
\item \texttt{u i} : undo what has been done to the call numbered \texttt{i} and redo it.
\end{itemize}

\section{Information about the Picat System}
The \texttt{sys} module contains a number of built-ins that display information about the Picat system.  This information includes statistics about the system, including the memory that is used, and the amount of time that it takes to perform a goal.

\subsection{Statistics}
The following built-ins display statistics about the memory that Picat system uses.
\begin{itemize}
\item \texttt{statistics}\index{\texttt{statistics/0}}: This predicate displays the number of bytes that are allocated to each data area, and the number of bytes that are already in use.
\item \texttt{statistics($Key$,$Value$)}\index{\texttt{statistics/2}}: The statistics concerning $Key$ are $Value$.  This predicate gives multiple solutions upon backtracking.  Keys include \texttt{runtime}, \texttt{program}, \texttt{heap}, \texttt{control}, \texttt{trail}, \texttt{table}, \texttt{gc}, \texttt{backtracks}, and \texttt{gc\_time}.  The values for most of the keys are lists of two elements.  For the key \texttt{runtime}, the first element denotes the amount of time in milliseconds that has elapsed since Picat started, and the second element denotes the amount of time that has elapsed since the previous call to \texttt{statistics/2}\index{\texttt{statistics/2}} was executed.  For the key \texttt{gc}, the number indicates the number of times that the garbage collector\index{garbage collector} has been invoked.  For the key \texttt{backtracks}, the number indicates the number of backtracks that have been done during the labeling of finite domain variables since Picat was started.  For all other keys, the first element denotes the size of memory in use, and the second element denotes the size of memory that is still available in the corresponding data area.
\item \texttt{statistics\_all() = $List$}\index{\texttt{statistics\_all/0}}: This function returns a list of lists that are in the form \texttt{[Key, Value]}.  The list contains all of the keys that \texttt{statistics/2}\index{\texttt{statistics/2}} can display, together with their corresponding values.
\end{itemize} 

\subsection*{Example}
\begin{verbatim}
Picat> statistics
      Stack+Heap:    8,000,000 bytes
        Stack in use:    1,156 bytes
        Heap in use:    28,592 bytes
      
      Program:       8,000,000 bytes
        In use:      1,448,436 bytes
        Symbols:         5,300
      
      Trail:         4,000,000 bytes
        In use:            936 bytes
      
      Memory manager:
         GC:         Call(0), Time(0 ms)
         Expansions: Stack+Heap(0), Program(0), Trail(0), Table(0)

Picat> statistics(Key, Value)
      Key = runtime
      Value = [359947,66060]?;

      Key = program
      Value = [1451656,6548344]?;

      Key = heap
      Value = [34112,7964524]?;

      Key = control
      Value = [1360,7964524]?;

      Key = trail
      Value = [1496,3998504]?;

      Key = table
      Value = [0,4000000]?;

      Key = table_blocks
      Value = 1?;

      key = gc
      Value = 0?;

      Key = backtracks
      V = 0 ?;

      Key = gc_time
      Value = 0 

Picat> L = statistics_all()
L = [[runtime, [359947,66060]], [program, [1451656,6548344]], 
     [heap, [34112,7964524]], [control, [1360,7964524]], 
     [trail, [1496,3998504]], [table, [0,4000000]], 
     [table_blocks,1],[gc, 0], [backtracks, 0], [gc_time, 0]]
\end{verbatim}

\subsection{Time}
The following predicates display the amount of CPU time that it takes to perform a goal.
\begin{itemize}
\item \texttt{time($Goal$)}\index{\texttt{time/1}}: This predicate calls $Goal$, and reports the number of seconds of CPU time that were consumed by the execution.
\item \texttt{time2($Goal$)}\index{\texttt{time2/1}}: This predicate calls $Goal$, and reports the number of seconds of CPU time that were consumed by the execution, and the number of backtracks that have been performed in labeling finite-domain variables during the execution of $Goal$.
\item \texttt{time\_out($Goal$,$Limit$,$Result$)}\index{\texttt{time\_out/3}}: This predicate is logically equivalent to \texttt{once $Goal$}\index{\texttt{once/1}}, except that is imposes a time limit, in milliseconds, on the evaluation.  If $Goal$ is not finished when $Limit$ expires, then the evaluation will be aborted, and $Result$ will be unified with the atom \texttt{time\_out}.  If $Goal$ succeeds within the time limit, then $Result$ will be unified with the atom \texttt{success}. Note that time-out may be delayed or never occur because of the execution of an external C function.
\end{itemize}

\subsection{Other System Information}
\begin{itemize}
\item \texttt{help}\index{\texttt{help/0}}: This predicate displays the usages of some of the commands that the system accepts.
\item \texttt{loaded\_modules() = $List$}:\index{\texttt{loaded\_modules/0}} This function returns a list of the modules that are currently loaded in the Picat system.  This list includes library modules and user-defined modules.  By default, this function returns \texttt{[basic,sys,io,math]}.
\item \texttt{nolog}\index{\texttt{nolog/0}}: This predicate turns off the logging flag.
\item \texttt{picat\_path() = $Path$}\index{\texttt{picat\_path/0}}: This function returns the directories that are stored in the environment variable \texttt{PICATPATH}.  If the environment variable \texttt{PICATPATH} does not exist, then this function throws an error.
\item \texttt{command($String$) = $Int$}\index{\texttt{command/1}}: This function sends the command $String$ to the OS and returns the status that is returned from the OS.
\end{itemize}

\ignore{
\section{The Table}
The \texttt{sys} module includes built-ins that initialize the table area, and built-ins that return answers to tabled goals.  For more about tabling, see Section \ref{chapter:tabling}.
\begin{itemize}
\item \texttt{initialize\_table}\index{\texttt{initialize\_table/0}}: This predicate initializes the table\index{tabling} area.   
\item \texttt{table\_get\_all($Goal$) = $List$}\index{\texttt{table\_get\_all/1}}:  This function returns a list of answers of the subgoals that are subsumed by $Goal$. For example, \texttt{table\_get\_all(\_)}\index{\texttt{table\_get\_all/1}} fetches all of the answers in the table\index{tabling}, since any subgoal is subsumed by the anonymous variable\index{anonymous variable}.
\item \texttt{table\_get\_one($Goal$)}\index{\texttt{table\_get\_one/1}}: If there is a subgoal in the subgoal table\index{tabling} that is a variant of \texttt{$Goal$}, and that has answers, then \texttt{$Goal$} is unified with the first answer. This predicate fails if there is no variant subgoal in the table\index{tabling}, or if there is no answer available.
\end{itemize}
}

\section{Garbage Collection}
Picat incorporates an incremental garbage collector\index{garbage collector} for the control stack and the heap.  The garbage collector\index{garbage collector} is active by default.  The \texttt{sys} module includes the following predicates for garbage collection\index{garbage collector}.
\begin{itemize}
\item \texttt{garbage\_collect}\index{\texttt{garbage\_collect/0}}: This predicate starts the garbage collector\index{garbage collector}.
\item \texttt{garbage\_collect($Size$)}\index{\texttt{garbage\_collect/1}}: This predicate calls the garbage collector\index{garbage collector}. If there are less than $Size$ words on the control stack and heap after garbage collection, then it invokes the memory manager to expand the stack and heap so that there are $Size$ words on the control stack and heap.
\end{itemize}

\section{Quitting the Picat System}
The following predicates can be used to terminate the Picat interpreter.
\begin{itemize}
\item \texttt{exit}\index{\texttt{exit/0}}
\item \texttt{halt}\index{\texttt{halt/0}}
\end{itemize}

\ignore{
\end{document}
}
