%{
//
dynload "libatsdoc/dynloadall.dats"
#include "utils/atsdoc/DOCUMENT/TUTORIALATS/tutorialatxt.dats"
//
#include "./ATEXT/ats2cairo.dats"
//
%}\
#comment("\n\
The file is automatically generated by [atsdoc] from chap_objtypes.atxt.\n\
")
#comment("\n\
Time of Generation: #timestamp()\
")
<chapter id="object_types">
#title("Types for Some Objects in Cairo")

#para('\
The type for cairo drawing contexts in ATS is declared as follows:\
')

#atscode('\
absvtype cairo_ref (l:addr) // = cairo_t*
')

#para('\

The type #stacode("cairo_ref(null)") is just for a null pointer.  Given an
address #emph("L") that is not null, the type
#stacode("cairo_ref")(#emph("L")) is for a reference to a cairo context
located at #emph("L"). We introduce an abbreviation #stacode("cairo_ref1")
as follows:\

')

#atscode('\
vtypedef cairo_ref1 = [l:addr | l > null] cairo_ref l
')

#para('\

Therefore, #stacode("cairo_ref1") essentially represents a type
#stacode("cairo_ref")(#emph("L")) for some unknown #emph("L") that is not
null. Similarly, we have the following types in ATS for objects
representing cairo surfaces, cairo patterns, and cairo font faces:\

')

#atscode('\
absvtype cairo_surface_ref (l:addr) // = cairo_surface_t*

absvtype cairo_pattern_ref (l:addr) // = cairo_pattern_t*
vtypedef cairo_pattern_ref1 = [l:addr | l > null] cairo_pattern_ref l

absvtype cairo_font_face_ref (l:addr) // = cairo_font_face_t*
vtypedef cairo_font_face_ref1 = [l:addr | l > null] cairo_font_face_ref l
')

#para('\

The above types for objects in cairo are all reference-counted. In other
words, there is a reference count in each object that is assgined one of
these types. When such an object is created, the initial count is 1. This
count can increase or decrease depending on operations performed on the
object, and the object is freed once the count drops to 0. In ATS, we can
employ linear types to track reference counts. Compared to various other
APIs for cairo, the ability to track reference counts statically, that is,
at compile-time, is arguably the greatest benefit one receives when
programming with ATS/Cairo.\

')

</chapter>#comment("chapter/object_types")

#comment(" ****** ****** ")

#comment(" end of [chap_objtypes.atxt] ")

%{
implement main () = fprint_filsub (stdout_ref, "chap_objtypes_atxt.txt")
%}
