Initializing

Constants

 apricot.h:
   #define FE(const_name) CONSTANT(fe,const_name)
   START_TABLE(fe,UV)
   #define feRead      1
   FE(Read)
   #define feWrite     2
   FE(Write)
   #define feException 4
   FE(Exception)
   END_TABLE(fe,UV)
   #undef FE

 Const.pm:
   package fe; *AUTOLOAD = \&Prima::Const::AUTOLOAD;

This code creates a structure of UV's ( unsigned integers ) and a register_fe_constants() function, which should be called at boot_Prima stage. This way feRead becomes C analog to fe::Read in perl.

Virtual method tables

Built-in classes already contain all information needed for method overloading, but when a new class is derived from existing one, new VMT is have to be created as well. The actual sub-classing is performed inside build_dynamic_vmt() and build_static_vmt(). gimme_the_vmt() function creates new VMT instance on the fly and caches the result for every new class that is derived from Prima class.

C to Perl and Perl to C calling routines

NB - Do not mix XS calls to xs language ( perlxs manpage) - the latter is a meta-language for simplification of coding tasks and is not used in Prima implementation.

It was decided not to code every function with XS calls, but instead use special wrapper functions ( also called "thunks") for every function that is called from within perl. Thunks are generated automatically by gencls tool ( prima-gencls manpage ), and typical Prima method consists of three functions, two of which are thunks.

First function, say Class_init(char*), would initialize a class ( for example). It is written fully in C, so in order to be called from perl code a registration step must be taken for a second function, Class_init_FROMPERL(), that would look like

   newXS( "Prima::Class::init", Class_init_FROMPERL, "Prima::Class");

Class_init_FROMPERL() is a first thunk, that translates the parameters passed from perl to C and the result back from C function to perl. This step is almost fully automatized, so one never bothers about writing XS code, the gencls utility creates the thunks code automatically.

Many C methods are called from within Prima C code using VMTs, but it is possible to override these methods from perl code. The actions for such a situation when a function is called from C but is an overridden method therefore must be taken. On that occasion the third function Class_init_REDEFINED() is declared. Its task is a reverse from Class_init_FROMPERL() - it conveys all C parameters to perl and return values from a perl function back to C. This thunk is also generated automatically by gencls tool.

As one can notice, only basic data types can be converted between C and perl, and at some point automated routines do not help. In such a situation data conversion code is written manually and is included into core C files. In the class declaration files these methods are prepended with 'public' or 'weird' modifiers, when methods with no special data handling needs use 'method' or 'static' modifiers.

NB - functions that are not allowed to be seen from perl have 'c_only' modifier, and therefore do not need thunk wrapping. These functions can nevertheless be overridden from C.

Built-in classes

    Object
        Component
                AbstractMenu
                        AccelTable
                        Menu
                        Popup
                Clipboard
                Drawable
                        DeviceBitmap
                        Printer
                        Image
                                Icon
                File
                Region
                Timer
                Widget
                        Application
                        Window

These classes can be seen from perl with Prima:: prefix. Along with these, Utils class is defined. Its only difference is that it cannot be used as a prototype for an object, and used merely as a package that binds functions. Classes that are not intended to be an object prototype marked with 'package' prefix, when others are marked with 'object' (see prima-gencls manpage).

Creation

Objects can be created from perl by using following code example:

   $obj = Prima::SampleObject-> create(
       name  => "Sample",
       index => 10,
   );

and from C:

   Handle obj;
   HV * profile = newHV();
   pset_c( name, "Sample");
   pset_i( index, 10);
   obj = Object_create("SampleObject", profile);
   sv_free(( SV*) profile);

Convenience pset_XX macros assign a value of XX type to the hash key given as a first parameter, to a hash variable named profile. "pset_i" works with integers, "pset_c" - with strings, etc.

Destruction

   $obj-> destroy

or from C

   Object_destroy( obj);

An object can be automatically destroyed when its reference count reaches 0. Note that the auto destruction would never happen if the object's reference count is not lowered after its creation. The code

   --SvREFCNT( SvRV( PAnyObject(object)-> mate));

is required if the object is to be returned to perl. If that code is not called, the object still could be destroyed explicitly, but its reference would still live, resulting in memory leak problem.

For user code it is sufficient to overload done() and/or cleanup() methods, or just onDestroy notifications. It is highly recommended to avoid overloading destroy method, since it can be called in re-entrant fashion. When overloading done(), be prepared that it may be called inside init(), and deal with the semi-initialized object.

Data instance

Object life stages

csConstructing

Initial stage, is set until create() is finished. Right after init() is completed, setup() method is called.

csNormal

After create() is finished and before destroy() started. If an object is csNormal and csConstructing stage, Object_alive() result would be non-zero.

csDestroying

destroy() started. This stage includes calling of cleanup() and done() routines.

csFrozen

cleanup() started.

csFinalizing

done() started

csDead

Destroy finished

Accessing object data

 ((PComponent) self)-> name; // classic C
 PComponent(self)-> name;    // using PComponent() macro from apricot.h
 var-> name;                 // using local var() macro

Object code could to be called also in several ways:

 (((PComponent) self)-> self)-> get_name( self); // classic C
 CComponent(self)-> get_name( self);             // using CComponent() macro from apricot.h
 my-> get_name( self);                           // using local my() macro

This calling is preferred, comparing to direct call of Component_get_name(), primarily because get_name() is a method and can be overridden from user code.

Calling perl code

   call_perl( Handle self, char * method, char * format, ...)
   sv_call_perl( SV * object, char * method, char * format, ...)
   cv_call_perl( SV * object, SV * code_reference, char * format, ...)

each character of format string represents a parameters type, and characters can be:

   'i' - integer
   's' - char *
   'n' - float
   'H' - Handle
   'S' - SV *
   'P' - Point
   'R' - Rect

The format string can be prepended with '<' character, in which case SV * scalar ( always scalar, even if code returns nothing or array ) value is returned. The caller is responsible for freeing the return value.

Exceptions

        SvTRUE( GvSV( errgv))

statement. It is guaranteed to be false if there was no exception condition. But in some situations, namely, when no perl_call_* functions are called or error value is already assigned before calling code, there is a wrapping technique that keeps previous error message and looks like:

    dG_EVAL_ARGS;                       // define arguments
    ....
    OPEN_G_EVAL;                        // open brackets
    // call code
    perl_call_method( ... | G_EVAL);    // G_EVAL is necessary
    if ( SvTRUE( GvSV( errgv)) {
        CLOSE_G_EVAL;                   // close brackets
        croak( SvPV_nolen( GvSV( errgv)));// propagate exception
        // no code is executed after croak
    }
    CLOSE_G_EVAL;                       // close brackets
    ...

This technique provides workaround to a "false alarm" situation, if SvTRUE( GvSV( errgv)) is true before perl_call_method().

Object protection

All C code that references to an object must check for its stage after every routine that switches to perl code, because the object might be destroyed inside the call. Typical code example would be like:

   function( Handle object) {
        int stage;
        protect_object( object);

        // call some perl code
        perl_call_method( object, "test", ...);

        stage = PObject(object)-> stage;
        unprotect_object( object);
        if ( stage == csDead) return;

        // proceed with the object
   }

Usual C code never checks for object stage before the call, because gimme_the_mate() function returns NULL if object's stage is csDead, and majority of Prima C code is prepended with this call, thus rejecting invalid references on early stage. If it is desired to get the C mate for objects that are in csDead stage, use "gimme_the_real_mate()" function instead.

init

   void
   Class_init( Handle self, HV * profile)
   {
      inherited init( self, profile);
      my-> set_index( pget_i( index));
      my-> set_name( pget_c( name));
   }

pget_XX macros call croak() if the profile key is not present into profile, but the mechanism guarantees that all keys that are listed in profile_default() are conveyed to init(). For explicit checking of key presence pexists() macro is used, and pdelete() is used for key deletion, although is it not recommended to use pdelete() inside init().

Object creation and returning

   static
   Handle xdup( Handle self, char * className)
   {
      Handle h;
      Point s;
      PDrawable i;

      // allocate a parameters hash
      HV * profile = newHV();

      // set all necessary arguments
      pset_H( owner,        var-> owner);
      pset_i( width,        var-> w);
      pset_i( height,       var-> h);
      pset_i( type,         (var-> type == dbtBitmap) ? imBW : imRGB);

      // create object
      h = Object_create( className, profile);

      // free profile, do not need it anymore
      sv_free(( SV *) profile);

      i = ( PDrawable) h;
      s = i-> self-> get_size( h);
      i-> self-> begin_paint( h);
      i-> self-> put_image_indirect( h, self, 0, 0, 0, 0, s.x, s.y, s.x, s.y, ropCopyPut);
      i-> self-> end_paint( h);

      // decrement reference count
      --SvREFCNT( SvRV( i-> mate));
      return h;
   }

Note that all code that would use this xdup(), have to increase and decrease object's reference count if some perl functions are to be executed before returning object to perl, otherwise it might be destroyed before its time.

       Handle x = xdup( self, "Prima::Image");
       ++SvREFCNT( SvRV( PAnyObject(x)-> mate)); // Code without these
       CImage( x)-> type( x, imbpp1);
       --SvREFCNT( SvRV( PAnyObject(x)-> mate)); // brackets is unsafe
       return x;

Attaching objects

Thus

    $c = Prima::Object-> create();

and Prima::Object-> create;

have different results. But for some classes, namely Widget ant its descendants, and also for Timer, AbstractMenu, Printer and Clipboard the code above would have same result - the objects would not be killed. That is because these objects call Component_attach() during init-stage, automatically increasing their reference count. Component_attach() and its reverse Component_detach() account list of objects, attributed to each other. Object can be attached to multiple objects, but cannot be attached more than once to another object.

Notifications

    Component_notify( self, "<sH", "Paint", self);
    Component_notify( self, "<sPii", "MouseDown", self, point, int, int);

Notifications mechanism accounts the reference list, similar to attach-detach mechanism, because all notifications can be attributed to different objects. The membership in this list does not affect the reference counting.

Multiple property setting

   $c-> set( index => 10, name  => "Sample" );

than to invoke several methods one by one. set() performs this calling itself, but for performance reasons it is possible to overload this method and code special conditions for multiple assignment. As an example, Prima::Image type conversion code is exemplified:

   void
   Image_set( Handle self, HV * profile)
   {
      ...
      if ( pexist( type))
      {
         int newType = pget_i( type);
         if ( !itype_supported( newType))
            warn("Invalid image type requested (%08x) in Image::set_type",
               newType);
         else
            if ( !opt_InPaint)
               my-> reset( self, newType, pexist( palette) ?
                  pget_sv( palette) : my->get_palette( self));
         pdelete( palette);
         pdelete( type);
      }
      ...
      inherited set ( self, profile);
   }

If type conversion is performed along with palette change, some efficiency is gained by supplying both 'type' and 'palette' parameters at a time. Moreover, because ordering of the fields is not determined by default ( although that be done by supplying '__ORDER__' hash key to set() }, it can easily be discovered that

    $image-> type( $a);
    $image-> palette( $b);

and

    $image-> palette( $b);
    $image-> type( $a);

produce different results. Therefore it might be only solution to code Class_set() explicitly.

If it is desired to specify exact order how atomic properties have to be called, __ORDER__ anonymous array have to be added to set() parameters.

   $image-> set(
      owner => $xxx,
      type  => 24,
      __ORDER__ => [qw( type owner)],
   );

Variables

primaObjects, PHash

Hash with all prima objects, where keys are their data instances

application, Handle

Pointer to an application. There can be only one Application instance at a time, or none at all.

Macros and functions

dG_EVAL_ARGS

Defines variable for $@ value storage

OPEN_G_EVAL, CLOSE_G_EVAL

Brackets for exception catching

build_static_vmt

 Bool(void * vmt)
    

Caches pre-built VMT for further use

build_dynamic_vmt

 Bool( void * vmt, char * ancestorName, int ancestorVmtSize)
    

Creates a subclass from vmt and caches result under ancestorName key

gimme_the_vmt

 PVMT( const char *className);
    

Returns VMT pointer associated with class by name.

gimme_the_mate

 Handle( SV * perlObject)
    

Returns a C pointer to an object, if perlObject is a reference to a Prima object. returns nilHandle if object's stage is csDead

gimme_the_real_mate

 Handle( SV * perlObject)
    

Returns a C pointer to an object, if perlObject is a reference to a Prima object. Same as "gimme_the_mate", but does not check for the object stage.

alloc1

 alloc1(type)
    

To be used instead (type*)(malloc(sizeof(type))

allocn

 allocn(type,n)
    

To be used instead (type*)(malloc((n)*sizeof(type))

alloc1z

Same as "alloc1" but fills the allocated memory with zeros

allocnz

Same as "allocn" but fills the allocated memory with zeros

prima_mallocz

Same as malloc() but fills the allocated memory with zeros

prima_hash_create

 PHash(void)
    

Creates an empty hash

prima_hash_destroy

 void(PHash self, Bool killAll);
    

Destroys a hash. If killAll is true, assumes that every value in the hash is a dynamic memory pointer and calls free() on each.

prima_hash_fetch

 void*( PHash self, const void *key, int keyLen);
    

Returns pointer to a value, if found, nil otherwise

prima_hash_delete

 void*( PHash self, const void *key, int keyLen, Bool kill);
    

Deletes hash key and returns associated value. if kill is true, calls free() on the value and returns nil.

prima_hash_store

 void( PHash self, const void *key, int keyLen, void *val);
    

Stores new value into hash. If the key is already present, old value is overwritten.

prima_hash_count

 int(PHash self)
    

Returns number of keys in the hash

prima_hash_first_that

 void * ( PHash self, void *action, void *params, int *pKeyLen, void **pKey);
    

Enumerates all hash entries, calling action procedure on each. If the action procedure returns true, enumeration stops and the last processed value is returned. Otherwise nil is returned. action have to be function declared as

 Bool action_callback( void * value, int keyLen, void * key, void * params);
    

params is a pointer to an arbitrary user data

kind_of

 Bool( Handle object, void *cls);
    

Returns true, if the object is an exemplar of class cls or its descendant

PERL_CALL_METHOD, PERL_CALL_PV

To be used instead of perl_call_method and perl_call_pv, described in perlguts manpage. These functions aliased to a code with the workaround of perl bug which emerges when G_EVAL flag is combined with G_SCALAR.

eval

 SV *( char *string)
    

Simplified perl_eval_pv() call.

sv_query_method

 CV * ( SV * object, char *methodName, Bool cacheIt);
    

Returns perl pointer to a method searched by a scalar and a name If cacheIt true, caches the hierarchy traverse result for a speedup.

query_method

 CV * ( Handle object, char *methodName, Bool cacheIt);
    

Returns perl pointer to a method searched by an object and a name If cacheIt true, caches the hierarchy traverse result for a speedup.

call_perl_indirect

 SV * ( Handle self, char *subName, const char *format, Bool cdecl,
        Bool coderef, va_list params);
    

Core function for calling Prima methods. Is used by the following three functions, but is never called directly. Format is described in "Calling perl code" section.

call_perl

 SV * ( Handle self, char *subName, const char *format, ...);
    

Calls method of an object pointer by a Handle

sv_call_perl

 SV * ( SV * mate, char *subName, const char *format, ...);
    

Calls method of an object pointed by a SV*

cv_call_perl

 SV * ( SV * mate, Sv * coderef, const char *format, ...);
    

Calls arbitrary perl code with mate as first parameter. Used in notifications mechanism.

Object_create

 Handle( char * className, HV * profile);
    

Creates an exemplar of className class with parameters in profile. Never returns nilHandle, throws an exception instead.

create_object

 void*( const char *objClass, const char *format, ...);
    

Convenience wrapper to Object_create. Uses format specification that is described in "Calling perl code".

create_instance

 Handle( const char * className)
    

Convenience call to "Object_create" with parameters in hash 'profile'.

Object_destroy

 void( Handle self);
    

Destroys object. One of few Prima function that can be called in re-entrant fashion.

Object_alive

 void( Handle self);
    

Returns non-zero is object is alive, 0 otherwise. In particular, current implementation returns 1 if object's stage is csNormal and 2 if it is csConstructing. Has virtually no use in C, only used in perl code.

protect_object

 void( Handle obj);
    

restricts object pointer from deletion after Object_destroy(). Can be called several times on an object. Increments Object. protectCount.

unprotect_object

 void( Handle obj);
    

Frees object pointer after Object. protectCount hits zero. Can be called several times on an object.

parse_hv

 HV *( I32 ax, SV **sp, I32 items, SV **mark, int expected, const char *methodName);
    

Transfers arguments in perl stack to a newly created HV and returns it.

push_hv

 void ( I32 ax, SV **sp, I32 items, SV **mark, int callerReturns, HV *hv);
    

Puts all hv contents back to perl stack.

push_hv_for_REDEFINED

 SV **( SV **sp, HV *hv);
    

Puts hv content as arguments to perl code to be called

pop_hv_for_REDEFINED

 int ( SV **sp, int count, HV *hv, int shouldBe);
    

Reads result of executed perl code and stores them into hv.

pexist

 Bool(char*key)
    

Return true if a key is present into hash 'profile'

pdelete

 void(char*key)
    

Deletes a key in hash 'profile'

pget_sv, pget_i, pget_f, pget_c, pget_H, pget_B

 TYPE(char*key)
    

Returns value of ( SV*, int, float, char*, Handle or Bool) that is associated to a key in hash 'profile'. Calls croak() if the key is not present.

pset_sv, pset_i, pset_f, pset_c, pset_H

 void( char*key, TYPE value)
    

Assigns a value to a key in hash 'profile' and increments reference count to a newly created scalar.

pset_b

 void( char*key, void* data, int length)
    

Assigns binary data to a key in hash 'profile' and increments reference count to a newly created scalar.

pset_sv_noinc

 void(char* key, SV * sv)
    

Assigns scalar value to a key in hash 'profile' without reference count increment.

duplicate_string

 char*( const char *)
    

Returns copy of a string

list_create

 void ( PList self, int size, int delta);
    

Creates a list instance with a static List structure.

plist_create

 PList( int size, int delta);
    

Created list instance and returns newly allocated List structure.

list_destroy

 void( PList self);
    

Destroys list data.

plist_destroy

 void ( PList self);
    

Destroys list data and frees list instance.

list_add

 int( PList self, Handle item);
    

Adds new item into a list, returns its index or -1 on error.

list_insert_at

 int ( PList self, Handle item, int pos);
    

Inserts new item into a list at a given position, returns its position or -1 on error.

list_at

 Handle ( PList self, int index);
    

Returns items that is located at given index or nilHandle if the index is out of range.

list_delete

 void( PList self, Handle item);
    

Removes the item from list.

list_delete_at

 void( PList self, int index);
    

Removes the item located at given index from a list.

list_delete_all

 void ( PList self, Bool kill);
    

Removes all items from the list. If kill is true, calls free() on every item before.

list_first_that

 int( PList self, void * action, void * params);
    

Enumerates all list entries, calling action procedure on each. If action returns true, enumeration stops and the index is returned. Otherwise -1 is returned. action have to be a function declared as

 Bool action_callback( Handle item, void * params);
    

params is a pointer to an arbitrary user data

list_index_of

 int( PList self, Handle item);
    

Returns index of an item, or -1 if the item is not in the list.