@c -*-texinfo-*-
@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2020 - 2022 Free Software Foundation, Inc.
@c See the file g-golf.texi for copying conditions.


@node Cache Park
@subsection Cache Park

Cache Park - Accessing G-Golf caches.


@subheading Procedures

@indentedblock
@table @code
@item @ref{gi-cache-show}
@item @ref{gi-cache-ref}
@c gi-cache-show
@c gi-cache-find
@end table
@end indentedblock


@subheading Variables

@indentedblock
@table @code
@item @ref{%gi-cache}
@end table
@end indentedblock


@subheading Description

G-Golf has and uses a cache @samp{mechanism} - actually several, but
only one is (partially) exposed to users (and with reserves, see
below), also referred to as G-Golf @code{main cache} - not only for
internal needs, but also to avoid reconstructing things
@samp{on-the-fly} unnecessarily, such as already imported
@ref{<gi-enum>}, @ref{<gi-flags>} and @ref{<gi-struct>} instances.

G-Golf @code{main cache} exposed functionality is @samp{access only} -
users should not (never) attempt to change its content - and its design
is not (yet) @samp{set in stone}, so interfaces here exposed, may (have
to be) change(d).

So, keeping the above reserves in mind, G-Golf @code{main cache} current
data structure is composed of two nested association lists, to which we
refer using @var{m-key} (main key) and @var{s-key} (secondary key). 


@subheading Procedures


@anchor{gi-cache-show}
@deffn Procedure gi-cache-show [m-key #f] 

Returns nothing.

Displays the content of G-Golf main cache. If @var{m-key} (main key) is
@code{#f} (the default), it displays the list of the main keys present
in the cache. Otherwise, it retrieves the content of the main cache for
@var{m-key} and displays its content if any, or @code{-- is empty --} if
none.
@end deffn


@anchor{gi-cache-ref}
@deffn Procedure gi-cache-ref m-key s-key

Returns a @ref{%gi-cache} entry or @code{#f}.

Obtains and returns the @ref{%gi-cache} entry for @var{m-key} and
@var{s-key}, or @code{#f} if none is found.

Remember that you may (always) view the list of main and secondary key
names (which is @samp{dynamic}, depending on what you have imported) by
calling @ref{gi-cache-show} (without or with an @var{m-key} arg
appropriately), but as a user, the two most important @var{m-key} are
@code{'enum} and @code{'flags}, so you may check their member names, or
bind their instance locally.

Main key names are given by G-Golf. Secondary key names are always the
result of calling @ref{g-name->name} upon the @samp{object} original
name.

For example, let's import, then retreive and visualize the content of
the @code{GtkPositionType} (enum) type:

@example
,use (g-golf)
(gi-import-by-name "Gtk" "PositionType")
@result{} $2 = #<<gi-enum> 7ff938938b40>

(gi-cache-ref 'enum 'gtk-position-type)
@result{} $3 = #<<gi-enum> 7ff938938b40>

(describe $3)
@print{} #<<gi-enum> 7ff938938b40> is an instance of class <gi-enum>
@print{} Slots are: 
@print{}     enum-set = ((left . 0) (right . 1) (top . 2) (bottom . 3))
@print{}     g-type = 94673466933568
@print{}     g-name = "GtkPositionType"
@print{}     name = gtk-position-type
@end example
@end deffn


@subheading Variables

@anchor{%gi-cache}
@defvar %gi-cache

Holds a reference the the G-Golf @code{main cache}, which as said
earlier, currently is composed of two nested association lists.
@end defvar
