
@c Extracted automatically from ../jit/jit-type.c - DO NOT EDIT


@cindex jit-type.h
@tindex jit_type_t

The functions that are defined in @code{<jit/jit-type.h>} allow
the library user to create and manipulate objects that represent
native system types.  For example, @code{jit_type_int} represents
the signed 32-bit integer type.

Each @code{jit_type_t} object represents a basic system type,
be it a primitive, a struct, a union, a pointer, or a function signature.
The library uses this information to lay out values in memory.

The following pre-defined types are available:

@table @code
@vindex jit_type_void
@item jit_type_void
Represents the @code{void} type.

@vindex jit_type_sbyte
@item jit_type_sbyte
Represents a signed 8-bit integer type.

@vindex jit_type_ubyte
@item jit_type_ubyte
Represents an unsigned 8-bit integer type.

@vindex jit_type_short
@item jit_type_short
Represents a signed 16-bit integer type.

@vindex jit_type_ushort
@item jit_type_ushort
Represents an unsigned 16-bit integer type.

@vindex jit_type_int
@item jit_type_int
Represents a signed 32-bit integer type.

@vindex jit_type_uint
@item jit_type_uint
Represents an unsigned 32-bit integer type.

@vindex jit_type_nint
@item jit_type_nint
Represents a signed integer type that has the same size and
alignment as a native pointer.

@vindex jit_type_nuint
@item jit_type_nuint
Represents an unsigned integer type that has the same size and
alignment as a native pointer.

@vindex jit_type_long
@item jit_type_long
Represents a signed 64-bit integer type.

@vindex jit_type_ulong
@item jit_type_ulong
Represents an unsigned 64-bit integer type.

@vindex jit_type_float32
@item jit_type_float32
Represents a 32-bit floating point type.

@vindex jit_type_float64
@item jit_type_float64
Represents a 64-bit floating point type.

@vindex jit_type_nfloat
@item jit_type_nfloat
Represents a floating point type that represents the greatest
precision supported on the native platform.

@vindex jit_type_void_ptr
@item jit_type_void_ptr
Represents the system's @code{void *} type.  This can be used wherever
a native pointer type is required.
@end table

Type descriptors are reference counted.  You can make a copy of a type
descriptor using the @code{jit_type_copy} function, and free the copy with
@code{jit_type_free}.

Some languages have special versions of the primitive numeric types
(e.g. boolean types, 16-bit Unicode character types, enumerations, etc).
If it is important to distinguish these special versions from the
numeric types, then you should use the @code{jit_type_create_tagged}
function below.

The following types correspond to the system types on the local
platform.  i.e. @code{jit_type_sys_int} will be the same size as
@code{long} on the local platform, whereas @code{jit_type_long} is
always 64 bits in size.  These types should not be used to compile
code that is intended to work identically on all platforms:

@table @code
@vindex jit_type_sys_bool
@item jit_type_sys_bool
Corresponds to the system @code{bool} type.

@vindex jit_type_sys_char
@item jit_type_sys_char
Corresponds to the system @code{char} type.  This may be either signed
or unsigned, depending upon the underlying system.

@vindex jit_type_sys_schar
@item jit_type_sys_schar
Corresponds to the system @code{signed char} type.

@vindex jit_type_sys_uchar
@item jit_type_sys_uchar
Corresponds to the system @code{unsigned char} type.

@vindex jit_type_sys_short
@item jit_type_sys_short
Corresponds to the system @code{short} type.

@vindex jit_type_sys_ushort
@item jit_type_sys_ushort
Corresponds to the system @code{unsigned short} type.

@vindex jit_type_sys_int
@item jit_type_sys_int
Corresponds to the system @code{int} type.

@vindex jit_type_sys_uint
@item jit_type_sys_uint
Corresponds to the system @code{unsigned int} type.

@vindex jit_type_sys_long
@item jit_type_sys_long
Corresponds to the system @code{long} type.

@vindex jit_type_sys_ulong
@item jit_type_sys_ulong
Corresponds to the system @code{unsigned long} type.

@vindex jit_type_sys_longlong
@item jit_type_sys_longlong
Corresponds to the system @code{long long} type (@code{__int64} under Win32).

@vindex jit_type_sys_ulonglong
@item jit_type_sys_ulonglong
Corresponds to the system @code{unsigned long long} type
(@code{unsigned __int64} under Win32).

@vindex jit_type_sys_float
@item jit_type_sys_float
Corresponds to the system @code{float} type.

@vindex jit_type_sys_double
@item jit_type_sys_double
Corresponds to the system @code{double} type.

@vindex jit_type_sys_long_double
@item jit_type_sys_long_double
Corresponds to the system @code{long double} type.
@end table


@deftypefun jit_type_t jit_type_copy (jit_type_t @var{type})
Make a copy of the type descriptor @var{type} by increasing
its reference count.
@end deftypefun

@deftypefun void jit_type_free (jit_type_t @var{type})
Free a type descriptor by decreasing its reference count.
This function is safe to use on pre-defined types, which are
never actually freed.
@end deftypefun

@deftypefun jit_type_t jit_type_create_struct (jit_type_t *@var{fields}, unsigned int @var{num_fields}, int @var{incref})
Create a type descriptor for a structure.  Returns NULL if out of memory.
If there are no fields, then the size of the structure will be zero.
It is necessary to add a padding field if the language does not allow
zero-sized structures.  The reference counts on the field types are
incremented if @var{incref} is non-zero.

The @code{libjit} library does not provide any special support for
implementing structure inheritance, where one structure extends the
definition of another.  The effect of inheritance can be achieved
by always allocating the first field of a structure to be an instance
of the inherited structure.  Multiple inheritance can be supported
by allocating several special fields at the front of an inheriting
structure.

Similarly, no special support is provided for vtables.  The program
is responsible for allocating an appropriate slot in a structure to
contain the vtable pointer, and dereferencing it wherever necessary.
The vtable will itself be a structure, containing signature types
for each of the method slots.

The choice not to provide special support for inheritance and vtables
in @code{libjit} was deliberate.  The layout of objects and vtables
is highly specific to the language and virtual machine being emulated,
and no single scheme can hope to capture all possibilities.
@end deftypefun

@deftypefun jit_type_t jit_type_create_union (jit_type_t *@var{fields}, unsigned int @var{num_fields}, int @var{incref})
Create a type descriptor for a union.  Returns NULL if out of memory.
If there are no fields, then the size of the union will be zero.
It is necessary to add a padding field if the language does not allow
zero-sized unions.  The reference counts on the field types are
incremented if @var{incref} is non-zero.
@end deftypefun

@deftypefun jit_type_t jit_type_create_signature (jit_abi_t @var{abi}, jit_type_t @var{return_type}, jit_type_t *@var{params}, unsigned int @var{num_params}, int @var{incref})
Create a type descriptor for a function signature.  Returns NULL if out
of memory.  The reference counts on the component types are incremented
if @var{incref} is non-zero.

When used as a structure or union field, function signatures are laid
out like pointers.  That is, they represent a pointer to a function
that has the specified parameters and return type.

@tindex jit_abi_t
The @var{abi} parameter specifies the Application Binary Interface (ABI)
that the function uses.  It may be one of the following values:

@table @code
@vindex jit_abi_cdecl
@item jit_abi_cdecl
Use the native C ABI definitions of the underlying platform.

@vindex jit_abi_vararg
@item jit_abi_vararg
Use the native C ABI definitions of the underlying platform,
and allow for an optional list of variable argument parameters.

@vindex jit_abi_stdcall
@item jit_abi_stdcall
Use the Win32 STDCALL ABI definitions, whereby the callee pops
its arguments rather than the caller.  If the platform does
not support this type of ABI, then @code{jit_abi_stdcall} will be
identical to @code{jit_abi_cdecl}.

@vindex jit_abi_fastcall
@item jit_abi_fastcall
Use the Win32 FASTCALL ABI definitions, whereby the callee pops
its arguments rather than the caller, and the first two word
arguments are passed in ECX and EDX.  If the platform does
not support this type of ABI, then @code{jit_abi_fastcall} will be
identical to @code{jit_abi_cdecl}.
@end table
@end deftypefun

@deftypefun jit_type_t jit_type_create_pointer (jit_type_t @var{type}, int @var{incref})
Create a type descriptor for a pointer to another type.  Returns NULL
if out of memory.  The reference count on @var{type} is incremented if
@var{incref} is non-zero.
@end deftypefun

@deftypefun jit_type_t jit_type_create_tagged (jit_type_t @var{type}, int @var{kind}, void *@var{data}, jit_meta_free_func @var{free_func}, int @var{incref})
Tag a type with some additional user data.  Tagging is typically used by
higher-level programs to embed extra information about a type that
@code{libjit} itself does not support.

As an example, a language might have a 16-bit Unicode character type
and a 16-bit unsigned integer type that are distinct types, even though
they share the same fundamental representation (@code{jit_ushort}).
Tagging allows the program to distinguish these two types, when
it is necessary to do so, without affecting @code{libjit}'s ability
to compile the code efficiently.

The @var{kind} is a small positive integer value that the program
can use to distinguish multiple tag types.  The @var{data} pointer is
the actual data that you wish to store.  And @var{free_func} is a
function that is used to free @var{data} when the type is freed
with @code{jit_type_free}.

If you need to store more than one piece of information, you can
tag a type multiple times.  The order in which multiple tags are
applied is irrelevant to @code{libjit}, although it may be relevant
to the higher-level program.

Tag kinds of 10000 or greater are reserved for @code{libjit} itself.
The following special tag kinds are currently provided in the
base implementation:

@table @code
@vindex JIT_TYPETAG_NAME
@item JIT_TYPETAG_NAME
The @var{data} pointer is a @code{char *} string indicating a friendly
name to display for the type.

@vindex JIT_TYPETAG_STRUCT_NAME
@vindex JIT_TYPETAG_UNION_NAME
@vindex JIT_TYPETAG_ENUM_NAME
@item JIT_TYPETAG_STRUCT_NAME
@itemx JIT_TYPETAG_UNION_NAME
@itemx JIT_TYPETAG_ENUM_NAME
The @var{data} pointer is a @code{char *} string indicating a friendly
name to display for a @code{struct}, @code{union}, or @code{enum} type.
This is for languages like C that have separate naming scopes for
typedef's and structures.

@vindex JIT_TYPETAG_CONST
@item JIT_TYPETAG_CONST
The underlying value is assumed to have @code{const} semantics.
The @code{libjit} library doesn't enforce such semantics: it is
up to the front-end to only use constant values in appopriate contexts.

@vindex JIT_TYPETAG_VOLATILE
@item JIT_TYPETAG_VOLATILE
The underlying value is assumed to be volatile.  The @code{libjit}
library will automatically call @code{jit_value_set_volatile} when a
value is constructed using this type.

@vindex JIT_TYPETAG_REFERENCE
@item JIT_TYPETAG_REFERENCE
The underlying value is a pointer, but it is assumed to refer to a
pass-by-reference parameter.

@vindex JIT_TYPETAG_OUTPUT
@item JIT_TYPETAG_OUTPUT
This is similar to @code{JIT_TYPETAG_REFERENCE}, except that the
underlying parameter is assumed to be output-only.

@vindex JIT_TYPETAG_RESTRICT
@item JIT_TYPETAG_RESTRICT
The underlying type is marked as @code{restrict}.  Normally ignored.

@vindex JIT_TYPETAG_SYS_BOOL
@vindex JIT_TYPETAG_SYS_CHAR
@vindex JIT_TYPETAG_SYS_SCHAR
@vindex JIT_TYPETAG_SYS_UCHAR
@vindex JIT_TYPETAG_SYS_SHORT
@vindex JIT_TYPETAG_SYS_USHORT
@vindex JIT_TYPETAG_SYS_INT
@vindex JIT_TYPETAG_SYS_UINT
@vindex JIT_TYPETAG_SYS_LONG
@vindex JIT_TYPETAG_SYS_ULONG
@vindex JIT_TYPETAG_SYS_LONGLONG
@vindex JIT_TYPETAG_SYS_ULONGLONG
@vindex JIT_TYPETAG_SYS_FLOAT
@vindex JIT_TYPETAG_SYS_DOUBLE
@vindex JIT_TYPETAG_SYS_LONGDOUBLE
@item JIT_TYPETAG_SYS_BOOL
@itemx JIT_TYPETAG_SYS_CHAR
@itemx JIT_TYPETAG_SYS_SCHAR
@itemx JIT_TYPETAG_SYS_UCHAR
@itemx JIT_TYPETAG_SYS_SHORT
@itemx JIT_TYPETAG_SYS_USHORT
@itemx JIT_TYPETAG_SYS_INT
@itemx JIT_TYPETAG_SYS_UINT
@itemx JIT_TYPETAG_SYS_LONG
@itemx JIT_TYPETAG_SYS_ULONG
@itemx JIT_TYPETAG_SYS_LONGLONG
@itemx JIT_TYPETAG_SYS_ULONGLONG
@itemx JIT_TYPETAG_SYS_FLOAT
@itemx JIT_TYPETAG_SYS_DOUBLE
@itemx JIT_TYPETAG_SYS_LONGDOUBLE
Used to mark types that we know for a fact correspond to the system
C types of the corresponding names.  This is primarily used to distinguish
system types like @code{int} and @code{long} types on 32-bit platforms
when it is necessary to do so.  The @code{jit_type_sys_xxx} values are
all tagged in this manner.
@end table
@end deftypefun

@deftypefun int jit_type_set_names (jit_type_t @var{type}, char **@var{names}, unsigned int @var{num_names})
Set the field or parameter names for @var{type}.  Returns zero
if there is insufficient memory to set the names.

Normally fields are accessed via their index.  Field names are a
convenience for front ends that prefer to use names to indices.
@end deftypefun

@deftypefun void jit_type_set_size_and_alignment (jit_type_t @var{type}, jit_nint @var{size}, jit_nint @var{alignment})
Set the size and alignment information for a structure or union
type.  Use this for performing explicit type layout.  Normally
the size is computed automatically.  Ignored if not a
structure or union type.  Setting either value to -1 will cause
that value to be computed automatically.
@end deftypefun

@deftypefun void jit_type_set_offset (jit_type_t @var{type}, unsigned int @var{field_index}, jit_nuint @var{offset})
Set the offset of a specific structure field.  Use this for
performing explicit type layout.  Normally the offset is
computed automatically.  Ignored if not a structure type,
or the field index is out of range.
@end deftypefun

@deftypefun int jit_type_get_kind (jit_type_t @var{type})
Get a value that indicates the kind of @var{type}.  This allows
callers to quickly classify a type to determine how it should be
handled further.

@table @code
@vindex JIT_TYPE_INVALID
@item JIT_TYPE_INVALID
The value of the @var{type} parameter is NULL.

@vindex JIT_TYPE_VOID
@item JIT_TYPE_VOID
The type is @code{jit_type_void}.

@vindex JIT_TYPE_SBYTE
@item JIT_TYPE_SBYTE
The type is @code{jit_type_sbyte}.

@vindex JIT_TYPE_UBYTE
@item JIT_TYPE_UBYTE
The type is @code{jit_type_ubyte}.

@vindex JIT_TYPE_SHORT
@item JIT_TYPE_SHORT
The type is @code{jit_type_short}.

@vindex JIT_TYPE_USHORT
@item JIT_TYPE_USHORT
The type is @code{jit_type_ushort}.

@vindex JIT_TYPE_INT
@item JIT_TYPE_INT
The type is @code{jit_type_int}.

@vindex JIT_TYPE_UINT
@item JIT_TYPE_UINT
The type is @code{jit_type_uint}.

@vindex JIT_TYPE_NINT
@item JIT_TYPE_NINT
The type is @code{jit_type_nint}.

@vindex JIT_TYPE_NUINT
@item JIT_TYPE_NUINT
The type is @code{jit_type_nuint}.

@vindex JIT_TYPE_LONG
@item JIT_TYPE_LONG
The type is @code{jit_type_long}.

@vindex JIT_TYPE_ULONG
@item JIT_TYPE_ULONG
The type is @code{jit_type_ulong}.

@vindex JIT_TYPE_FLOAT32
@item JIT_TYPE_FLOAT32
The type is @code{jit_type_float32}.

@vindex JIT_TYPE_FLOAT64
@item JIT_TYPE_FLOAT64
The type is @code{jit_type_float64}.

@vindex JIT_TYPE_NFLOAT
@item JIT_TYPE_NFLOAT
The type is @code{jit_type_nfloat}.

@vindex JIT_TYPE_STRUCT
@item JIT_TYPE_STRUCT
The type is the result of calling @code{jit_type_create_struct}.

@vindex JIT_TYPE_UNION
@item JIT_TYPE_UNION
The type is the result of calling @code{jit_type_create_union}.

@vindex JIT_TYPE_SIGNATURE
@item JIT_TYPE_SIGNATURE
The type is the result of calling @code{jit_type_create_signature}.

@vindex JIT_TYPE_PTR
@item JIT_TYPE_PTR
The type is the result of calling @code{jit_type_create_pointer}.
@end table

@vindex JIT_TYPE_FIRST_TAGGED
If this function returns @code{JIT_TYPE_FIRST_TAGGED} or higher,
then the type is tagged and its tag kind is the return value minus
@code{JIT_TYPE_FIRST_TAGGED}.  That is, the following two expressions
will be identical if @var{type} is tagged:

@example
jit_type_get_tagged_kind(type)
jit_type_get_kind(type) - JIT_TYPE_FIRST_TAGGED
@end example
@end deftypefun

@deftypefun jit_nuint jit_type_get_size (jit_type_t @var{type})
Get the size of a type in bytes.
@end deftypefun

@deftypefun jit_nuint jit_type_get_alignment (jit_type_t @var{type})
Get the alignment of a type.  An alignment value of 2 indicates
that the type should be aligned on a two-byte boundary, for example.
@end deftypefun

@deftypefun {unsigned int} jit_type_num_fields (jit_type_t @var{type})
Get the number of fields in a structure or union type.
@end deftypefun

@deftypefun jit_type_t jit_type_get_field (jit_type_t @var{type}, unsigned int @var{field_index})
Get the type of a specific field within a structure or union.
Returns NULL if not a structure or union, or the index is out of range.
@end deftypefun

@deftypefun jit_nuint jit_type_get_offset (jit_type_t @var{type}, unsigned int @var{field_index})
Get the offset of a specific field within a structure.
Returns zero if not a structure, or the index is out of range,
so this is safe to use on non-structure types.
@end deftypefun

@deftypefun {const char *} jit_type_get_name (jit_type_t @var{type}, unsigned int @var{index})
Get the name of a structure, union, or signature field/parameter.
Returns NULL if not a structure, union, or signature, the index
is out of range, or there is no name associated with the component.
@end deftypefun

@deftypefun {unsigned int} jit_type_find_name (jit_type_t @var{type}, const char *@var{name})
Find the field/parameter index for a particular name.  Returns
@code{JIT_INVALID_NAME} if the name was not present.
@end deftypefun

@deftypefun {unsigned int} jit_type_num_params (jit_type_t @var{type})
Get the number of parameters in a signature type.
@end deftypefun

@deftypefun jit_type_t jit_type_get_return (jit_type_t @var{type})
Get the return type from a signature type.  Returns NULL if
not a signature type.
@end deftypefun

@deftypefun jit_type_t jit_type_get_param (jit_type_t @var{type}, unsigned int @var{param_index})
Get a specific parameter from a signature type.  Returns NULL
if not a signature type or the index is out of range.
@end deftypefun

@deftypefun jit_abi_t jit_type_get_abi (jit_type_t @var{type})
Get the ABI code from a signature type.  Returns @code{jit_abi_cdecl}
if not a signature type.
@end deftypefun

@deftypefun jit_type_t jit_type_get_ref (jit_type_t @var{type})
Get the type that is referred to by a pointer type.  Returns NULL
if not a pointer type.
@end deftypefun

@deftypefun jit_type_t jit_type_get_tagged_type (jit_type_t @var{type})
Get the type that underlies a tagged type.  Returns NULL
if not a tagged type.
@end deftypefun

@deftypefun void jit_type_set_tagged_type (jit_type_t @var{type}, jit_type_t @var{underlying})
Set the type that underlies a tagged type.  Ignored if @var{type}
is not a tagged type.  If @var{type} already has an underlying
type, then the original is freed.

This function is typically used to flesh out the body of a
forward-declared type.  The tag is used as a placeholder
until the definition can be located.
@end deftypefun

@deftypefun int jit_type_get_tagged_type (jit_type_t @var{type})
Get the kind of tag that is applied to a tagged type.  Returns -1
if not a tagged type.
@end deftypefun

@deftypefun {void *} jit_type_get_tagged_data (jit_type_t @var{type})
Get the user data is associated with a tagged type.  Returns NULL
if not a tagged type.
@end deftypefun

@deftypefun void jit_type_set_tagged_data (jit_type_t @var{type}, void *@var{data}, jit_meta_free_func @var{free_func})
Set the user data is associated with a tagged type.  The original data,
if any, is freed.
@end deftypefun

@deftypefun int jit_type_is_primitive (jit_type_t @var{type})
Determine if a type is primitive.
@end deftypefun

@deftypefun int jit_type_is_struct (jit_type_t @var{type})
Determine if a type is a structure.
@end deftypefun

@deftypefun int jit_type_is_union (jit_type_t @var{type})
Determine if a type is a union.
@end deftypefun

@deftypefun int jit_type_is_signature (jit_type_t @var{type})
Determine if a type is a function signature.
@end deftypefun

@deftypefun int jit_type_is_pointer (jit_type_t @var{type})
Determine if a type is a pointer.
@end deftypefun

@deftypefun int jit_type_is_tagged (jit_type_t @var{type})
Determine if a type is a tagged type.
@end deftypefun

@deftypefun jit_nuint jit_type_best_alignment (void)
Get the best alignment value for this platform.
@end deftypefun

@deftypefun jit_type_t jit_type_normalize (jit_type_t @var{type})
Normalize a type to its basic numeric form.  e.g. "jit_type_nint" is
turned into "jit_type_int" or "jit_type_long", depending upon
the underlying platform.  Pointers are normalized like "jit_type_nint".
If the type does not have a normalized form, it is left unchanged.

Normalization is typically used prior to applying a binary numeric
instruction, to make it easier to determine the common type.
It will also remove tags from the specified type.
@end deftypefun

@deftypefun jit_type_t jit_type_remove_tags (jit_type_t @var{type})
Remove tags from a type, and return the underlying type.
This is different from normalization, which will also collapses
native types to their basic numeric counterparts.
@end deftypefun

@deftypefun jit_type_t jit_type_promote_int (jit_type_t @var{type})
If @var{type} is @code{jit_type_sbyte} or @code{jit_type_short},
then return @code{jit_type_int}.  If @var{type} is
@code{jit_type_ubyte} or @code{jit_type_ushort}, then return
@code{jit_type_uint}.  Otherwise return @var{type} as-is.
@end deftypefun

@deftypefun int jit_type_return_via_pointer (jit_type_t @var{type})
Determine if a type should be returned via a pointer if it appears
as the return type in a signature.
@end deftypefun

@deftypefun int jit_type_has_tag (jit_type_t @var{type}, int @var{kind})
Determine if @var{type} has a specific kind of tag.  This will
resolve multiple levels of tagging.
@end deftypefun

