1pod::Prima::internals(3U)ser Contributed Perl Documentatipoond::Prima::internals(3)
2
3
4

NAME

6       Prima::internals - Prima internal architecture
7

DESCRIPTION

9       This documents elucidates the internal structures of the Prima toolkit,
10       its loading considerations, object and class representation and C
11       coding style.
12

Bootstrap

14   Initializing
15       For a perl script, Prima is no more but an average module that uses
16       DynaLoader. As 'use Prima' code gets executed, a bootstrap procedure
17       boot_Prima() is called. This procedure initializes all internal
18       structures and built-in Prima classes. It also initializes all system-
19       dependent structures, calling window_subsystem_init(). After that point
20       Prima module is ready to use. All wrapping code for built-in
21       functionality that can be seen from perl is located into two modules -
22       Prima::Const and Prima::Classes.
23
24   Constants
25       Prima defines lot of constants for different purposes ( e.g. colors,
26       font styles etc). Prima does not follow perl naming conventions here,
27       on the reason of simplicity.  It is ( arguably ) easier to write
28       cl::White rather than Prima::cl::White.  As perl constants are
29       functions to be called once ( that means that a constant's value is not
30       defined until it used first ), Prima registers these functions during
31       boot_Prima stage. As soon as perl code tries to get a constant's value,
32       an AUTOLOAD function is called, which is binded inside Prima::Const.
33       Constants are widely used both in C and perl code, and are defined in
34       apricot.h in that way so perl constant definition comes along with C
35       one.  As an example file event constants set is described here.
36
37        apricot.h:
38          #define FE(const_name) CONSTANT(fe,const_name)
39          START_TABLE(fe,UV)
40          #define feRead      1
41          FE(Read)
42          #define feWrite     2
43          FE(Write)
44          #define feException 4
45          FE(Exception)
46          END_TABLE(fe,UV)
47          #undef FE
48
49        Const.pm:
50          package fe; *AUTOLOAD = \&Prima::Const::AUTOLOAD;
51
52       This code creates a structure of UV's ( unsigned integers ) and a
53       register_fe_constants() function, which should be called at boot_Prima
54       stage. This way feRead becomes C analog to fe::Read in perl.
55

Classes and methods

57   Virtual method tables
58       Prima implementation of classes uses virtual method tables, or VMTs, in
59       order to make the classes inheritable and their methods overrideable.
60       The VMTs are usual C structs, that contain pointers to functions.  Set
61       of these functions represents a class. This chapter is not about OO
62       programming, you have to find a good book on it if you are not familiar
63       with the OO concepts, but in short, because Prima is written in C, not
64       in C++, it uses its own classes and objects implementation, so all
65       object syntax is devised from scratch.
66
67       Built-in classes already contain all information needed for method
68       overloading, but when a new class is derived from existing one, new VMT
69       is have to be created as well. The actual sub-classing is performed
70       inside build_dynamic_vmt() and build_static_vmt().  gimme_the_vmt()
71       function creates new VMT instance on the fly and caches the result for
72       every new class that is derived from Prima class.
73
74   C to Perl and Perl to C calling routines
75       Majority of Prima methods is written in C using XS perl routines, which
76       represent a natural ( from a perl programmer's view ) way of C to Perl
77       communication.  perlguts manpage describes these functions and macros.
78
79       NB - Do not mix XS calls to xs language ( perlxs manpage) - the latter
80       is a meta-language for simplification of coding tasks and is not used
81       in Prima implementation.
82
83       It was decided not to code every function with XS calls, but instead
84       use special wrapper functions ( also called "thunks") for every
85       function that is called from within perl. Thunks are generated
86       automatically by gencls tool ( prima-gencls manpage ), and typical
87       Prima method consists of three functions, two of which are thunks.
88
89       First function, say Class_init(char*), would initialize a class ( for
90       example).  It is written fully in C, so in order to be called from perl
91       code a registration step must be taken for a second function,
92       Class_init_FROMPERL(), that would look like
93
94          newXS( "Prima::Class::init", Class_init_FROMPERL, "Prima::Class");
95
96       Class_init_FROMPERL() is a first thunk, that translates the parameters
97       passed from perl to C and the result back from C function to perl.
98       This step is almost fully automatized, so one never bothers about
99       writing XS code, the gencls utility creates the thunks code
100       automatically.
101
102       Many C methods are called from within Prima C code using VMTs, but it
103       is possible to override these methods from perl code. The actions for
104       such a situation when a function is called from C but is an overridden
105       method therefore must be taken. On that occasion the third function
106       Class_init_REDEFINED() is declared. Its task is a reverse from
107       Class_init_FROMPERL() - it conveys all C parameters to perl and return
108       values from a perl function back to C. This thunk is also generated
109       automatically by gencls tool.
110
111       As one can notice, only basic data types can be converted between C and
112       perl, and at some point automated routines do not help. In such a
113       situation data conversion code is written manually and is included into
114       core C files.  In the class declaration files these methods are
115       prepended with 'public' or 'weird' modifiers, when methods with no
116       special data handling needs use 'method' or 'static' modifiers.
117
118       NB - functions that are not allowed to be seen from perl have 'c_only'
119       modifier, and therefore do not need thunk wrapping. These functions can
120       nevertheless be overridden from C.
121
122   Built-in classes
123       Prima defines the following built-in classes: (in hierarchy order)
124
125           Object
126               Component
127                       AbstractMenu
128                               AccelTable
129                               Menu
130                               Popup
131                       Clipboard
132                       Drawable
133                               DeviceBitmap
134                               Printer
135                               Image
136                                       Icon
137                       File
138                       Region
139                       Timer
140                       Widget
141                               Application
142                               Window
143
144       These classes can be seen from perl with Prima:: prefix.  Along with
145       these, Utils class is defined. Its only difference is that it cannot be
146       used as a prototype for an object, and used merely as a package that
147       binds functions.  Classes that are not intended to be an object
148       prototype marked with 'package' prefix, when others are marked with
149       'object' (see prima-gencls manpage).
150

Objects

152       This chapter deals only with Prima::Object descendants, pure perl
153       objects are not of interest here, so the 'object' term is thereafter
154       referenced to Prima::Object descendant object.  Prima employs blessed
155       hashes for its objects.
156
157   Creation
158       All built-in object classes and their descendants can be used for
159       creating objects with perl semantics. Perl objects are created by
160       calling bless(), but it is not enough to create Prima objects. Every
161       Prima::Object descendant class therefore is equipped with create()
162       method, that allocates object instance and calls bless() itself.
163       Parameters that come with create() call are formed into a hash and
164       passed to init() method, that is also present on every object. Note the
165       fact that although perl-coded init() returns the hash, it not seen in C
166       code. This is a special consideration for the methods that have 'HV *
167       profile' as a last parameter in their class declaration. The
168       corresponding thunk copies the hash content back to perl stack, using
169       parse_hv() and push_hv() functions.
170
171       Objects can be created from perl by using following code example:
172
173          $obj = Prima::SampleObject-> create(
174              name  => "Sample",
175              index => 10,
176          );
177
178       and from C:
179
180          Handle obj;
181          HV * profile = newHV();
182          pset_c( name, "Sample");
183          pset_i( index, 10);
184          obj = Object_create("SampleObject", profile);
185          sv_free(( SV*) profile);
186
187       Convenience pset_XX macros assign a value of XX type to the hash key
188       given as a first parameter, to a hash variable named profile. "pset_i"
189       works with integers, "pset_c" - with strings, etc.
190
191   Destruction
192       As well as create() method, every object class has destroy() method.
193       Object can be destroyed either from perl
194
195          $obj-> destroy
196
197       or from C
198
199          Object_destroy( obj);
200
201       An object can be automatically destroyed when its reference count
202       reaches 0. Note that the auto destruction would never happen if the
203       object's reference count is not lowered after its creation. The code
204
205          --SvREFCNT( SvRV( PAnyObject(object)-> mate));
206
207       is required if the object is to be returned to perl.  If that code is
208       not called, the object still could be destroyed explicitly, but its
209       reference would still live, resulting in memory leak problem.
210
211       For user code it is sufficient to overload done() and/or cleanup()
212       methods, or just onDestroy notifications. It is highly recommended to
213       avoid overloading destroy method, since it can be called in re-entrant
214       fashion. When overloading done(), be prepared that it may be called
215       inside init(), and deal with the semi-initialized object.
216
217   Data instance
218       All object data after their creation represent an object instance.  All
219       Prima objects are blessed hashes, and the hash key __CMATE__ holds a C
220       pointer to a memory which is occupied by C data instance, or a "mate".
221       It keeps all object variables and a pointer to VMT. Every object has
222       its own copy of data instance, but the VMTs can be shared. In order to
223       reach to C data instance gimme_the_mate() function is used. As a first
224       parameter it accepts a scalar (SV*), which is expected to be a
225       reference to a hash, and returns the C data instance if the scalar is a
226       Prima object.
227
228   Object life stages
229       It was decided to divide object life stage in several steps.  Every
230       stage is mirrored into PObject(self)-> stage integer variable, which
231       can be one of csXXX constants.  Currently it has six:
232
233       csConstructing
234           Initial stage, is set until create() is finished.  Right after
235           init() is completed, setup() method is called.
236
237       csNormal
238           After create() is finished and before destroy() started.  If an
239           object is csNormal and csConstructing stage, Object_alive() result
240           would be non-zero.
241
242       csDestroying
243           destroy() started. This stage includes calling of cleanup() and
244           done() routines.
245
246       csFrozen
247           cleanup() started.
248
249       csFinalizing
250           done() started
251
252       csDead
253           Destroy finished
254

Coding techniques

256   Accessing object data
257       C coding has no specific conventions, except when a code is an object
258       method. Object syntax for accessing object instance data is also fairly
259       standard.  For example, accessing component's field called 'name' can
260       be done in several ways:
261
262        ((PComponent) self)-> name; // classic C
263        PComponent(self)-> name;    // using PComponent() macro from apricot.h
264        var-> name;                 // using local var() macro
265
266       Object code could to be called also in several ways:
267
268        (((PComponent) self)-> self)-> get_name( self); // classic C
269        CComponent(self)-> get_name( self);             // using CComponent() macro from apricot.h
270        my-> get_name( self);                           // using local my() macro
271
272       This calling is preferred, comparing to direct call of
273       Component_get_name(), primarily because get_name() is a method and can
274       be overridden from user code.
275
276   Calling perl code
277       call_perl_indirect() function accepts object, its method name and
278       parameters list with parameter format string. It has several wrappers
279       for easier use, which are:
280
281          call_perl( Handle self, char * method, char * format, ...)
282          sv_call_perl( SV * object, char * method, char * format, ...)
283          cv_call_perl( SV * object, SV * code_reference, char * format, ...)
284
285       each character of format string represents a parameters type, and
286       characters can be:
287
288          'i' - integer
289          's' - char *
290          'n' - float
291          'H' - Handle
292          'S' - SV *
293          'P' - Point
294          'R' - Rect
295
296       The format string can be prepended with '<' character, in which case SV
297       * scalar ( always scalar, even if code returns nothing or array ) value
298       is returned. The caller is responsible for freeing the return value.
299
300   Exceptions
301       As descriped in perlguts manpage, G_EVAL flag is used in perl_call_sv()
302       and perl_call_method() to indicate that an eventual exception should
303       never be propagated automatically.  The caller checks if the exception
304       was taken place by evaluating
305
306               SvTRUE( GvSV( errgv))
307
308       statement. It is guaranteed to be false if there was no exception
309       condition. But in some situations, namely, when no perl_call_*
310       functions are called or error value is already assigned before calling
311       code, there is a wrapping technique that keeps previous error message
312       and looks like:
313
314           dG_EVAL_ARGS;                       // define arguments
315           ....
316           OPEN_G_EVAL;                        // open brackets
317           // call code
318           perl_call_method( ... | G_EVAL);    // G_EVAL is necessary
319           if ( SvTRUE( GvSV( errgv)) {
320               CLOSE_G_EVAL;                   // close brackets
321               croak( SvPV_nolen( GvSV( errgv)));// propagate exception
322               // no code is executed after croak
323           }
324           CLOSE_G_EVAL;                       // close brackets
325           ...
326
327       This technique provides workaround to a "false alarm" situation, if
328       SvTRUE( GvSV( errgv)) is true before perl_call_method().
329
330   Object protection
331       After the object destroy stage is completed, it is possible that
332       object's data instance is gone, and even simple stage check might cause
333       segmentation fault.  To avoid this, bracketing functions called
334       "protect_object()" and "unprotect_object()" are used.  protect_object()
335       increments reference count to the object instance, thus delaying its
336       freeing until decrementing unprotect_object() is called.
337
338       All C code that references to an object must check for its stage after
339       every routine that switches to perl code, because the object might be
340       destroyed inside the call. Typical code example would be like:
341
342          function( Handle object) {
343               int stage;
344               protect_object( object);
345
346               // call some perl code
347               perl_call_method( object, "test", ...);
348
349               stage = PObject(object)-> stage;
350               unprotect_object( object);
351               if ( stage == csDead) return;
352
353               // proceed with the object
354          }
355
356       Usual C code never checks for object stage before the call, because
357       gimme_the_mate() function returns NULL if object's stage is csDead, and
358       majority of Prima C code is prepended with this call, thus rejecting
359       invalid references on early stage. If it is desired to get the C mate
360       for objects that are in csDead stage, use "gimme_the_real_mate()"
361       function instead.
362
363   init
364       Object's method init() is responsible for setting all its initial
365       properties to the object, but all code that is executed inside init
366       must be aware that the object's stage is csConstructing. init()
367       consists of two parts: calling of ancestor's init() and setting
368       properties. Examples are many in both C and perl code, but in short it
369       looks like:
370
371          void
372          Class_init( Handle self, HV * profile)
373          {
374             inherited init( self, profile);
375             my-> set_index( pget_i( index));
376             my-> set_name( pget_c( name));
377          }
378
379       pget_XX macros call croak() if the profile key is not present into
380       profile, but the mechanism guarantees that all keys that are listed in
381       profile_default() are conveyed to init(). For explicit checking of key
382       presence pexists() macro is used, and pdelete() is used for key
383       deletion, although is it not recommended to use pdelete() inside
384       init().
385
386   Object creation and returning
387       As described is previous sections, there are some precautions to be
388       taken into account when an object is created inside C code.  A piece of
389       real code from DeviceBitmap.c would serve as an example:
390
391          static
392          Handle xdup( Handle self, char * className)
393          {
394             Handle h;
395             Point s;
396             PDrawable i;
397
398             // allocate a parameters hash
399             HV * profile = newHV();
400
401             // set all necessary arguments
402             pset_H( owner,        var-> owner);
403             pset_i( width,        var-> w);
404             pset_i( height,       var-> h);
405             pset_i( type,         (var-> type == dbtBitmap) ? imBW : imRGB);
406
407             // create object
408             h = Object_create( className, profile);
409
410             // free profile, do not need it anymore
411             sv_free(( SV *) profile);
412
413             i = ( PDrawable) h;
414             s = i-> self-> get_size( h);
415             i-> self-> begin_paint( h);
416             i-> self-> put_image_indirect( h, self, 0, 0, 0, 0, s.x, s.y, s.x, s.y, ropCopyPut);
417             i-> self-> end_paint( h);
418
419             // decrement reference count
420             --SvREFCNT( SvRV( i-> mate));
421             return h;
422          }
423
424       Note that all code that would use this xdup(), have to increase and
425       decrease object's reference count if some perl functions are to be
426       executed before returning object to perl, otherwise it might be
427       destroyed before its time.
428
429              Handle x = xdup( self, "Prima::Image");
430              ++SvREFCNT( SvRV( PAnyObject(x)-> mate)); // Code without these
431              CImage( x)-> type( x, imbpp1);
432              --SvREFCNT( SvRV( PAnyObject(x)-> mate)); // brackets is unsafe
433              return x;
434
435   Attaching objects
436       The newly created object returned from C would be destroyed due perl's
437       garbage cleaning mechanism right away, unless the object value would be
438       assigned to a scalar, for example.
439
440       Thus
441
442           $c = Prima::Object-> create();
443
444       and
445           Prima::Object-> create;
446
447       have different results. But for some classes, namely Widget ant its
448       descendants, and also for Timer, AbstractMenu, Printer and Clipboard
449       the code above would have same result - the objects would not be
450       killed. That is because these objects call Component_attach() during
451       init-stage, automatically increasing their reference count.
452       Component_attach() and its reverse Component_detach() account list of
453       objects, attributed to each other. Object can be attached to multiple
454       objects, but cannot be attached more than once to another object.
455
456   Notifications
457       All Prima::Component descendants are equipped with the mechanism that
458       allows multiple user callbacks routines to be called on different
459       events. This mechanism is used heavily in event-driven programming.
460       Component_notify() is used to call user notifications, and its format
461       string has same format as accepted by perl_call_indirect().  The only
462       difference that it always has to be prepended with '<s', - this way the
463       call success flag is set, and first parameter has to be the name of the
464       notification.
465
466           Component_notify( self, "<sH", "Paint", self);
467           Component_notify( self, "<sPii", "MouseDown", self, point, int, int);
468
469       Notifications mechanism accounts the reference list, similar to attach-
470       detach mechanism, because all notifications can be attributed to
471       different objects. The membership in this list does not affect the
472       reference counting.
473
474   Multiple property setting
475       Prima::Object method set() is designed to assign several properties at
476       one time. Sometimes it is more convenient to write
477
478          $c-> set( index => 10, name  => "Sample" );
479
480       than to invoke several methods one by one. set() performs this calling
481       itself, but for performance reasons it is possible to overload this
482       method and code special conditions for multiple assignment. As an
483       example, Prima::Image type conversion code is exemplified:
484
485          void
486          Image_set( Handle self, HV * profile)
487          {
488             ...
489             if ( pexist( type))
490             {
491                int newType = pget_i( type);
492                if ( !itype_supported( newType))
493                   warn("Invalid image type requested (%08x) in Image::set_type",
494                      newType);
495                else
496                   if ( !opt_InPaint)
497                      my-> reset( self, newType, pexist( palette) ?
498                         pget_sv( palette) : my->get_palette( self));
499                pdelete( palette);
500                pdelete( type);
501             }
502             ...
503             inherited set ( self, profile);
504          }
505
506       If type conversion is performed along with palette change, some
507       efficiency is gained by supplying both 'type' and 'palette' parameters
508       at a time.  Moreover, because ordering of the fields is not determined
509       by default ( although that be done by supplying '__ORDER__' hash key to
510       set() }, it can easily be discovered that
511
512           $image-> type( $a);
513           $image-> palette( $b);
514
515       and
516
517           $image-> palette( $b);
518           $image-> type( $a);
519
520       produce different results. Therefore it might be only solution to code
521       Class_set() explicitly.
522
523       If it is desired to specify exact order how atomic properties have to
524       be called, __ORDER__ anonymous array have to be added to set()
525       parameters.
526
527          $image-> set(
528             owner => $xxx,
529             type  => 24,
530             __ORDER__ => [qw( type owner)],
531          );
532

API reference

534   Variables
535       primaObjects, PHash
536           Hash with all prima objects, where keys are their data instances
537
538       application, Handle
539           Pointer to an application. There can be only one Application
540           instance at a time, or none at all.
541
542   Macros and functions
543       dG_EVAL_ARGS
544           Defines variable for $@ value storage
545
546       OPEN_G_EVAL, CLOSE_G_EVAL
547           Brackets for exception catching
548
549       build_static_vmt
550            Bool(void * vmt)
551
552           Caches pre-built VMT for further use
553
554       build_dynamic_vmt
555            Bool( void * vmt, char * ancestorName, int ancestorVmtSize)
556
557           Creates a subclass from vmt and caches result under ancestorName
558           key
559
560       gimme_the_vmt
561            PVMT( const char *className);
562
563           Returns VMT pointer associated with class by name.
564
565       gimme_the_mate
566            Handle( SV * perlObject)
567
568           Returns a C pointer to an object, if perlObject is a reference to a
569           Prima object. returns nilHandle if object's stage is csDead
570
571       gimme_the_real_mate
572            Handle( SV * perlObject)
573
574           Returns a C pointer to an object, if perlObject is a reference to a
575           Prima object. Same as "gimme_the_mate", but does not check for the
576           object stage.
577
578       alloc1
579            alloc1(type)
580
581           To be used instead (type*)(malloc(sizeof(type))
582
583       allocn
584            allocn(type,n)
585
586           To be used instead (type*)(malloc((n)*sizeof(type))
587
588       alloc1z
589           Same as "alloc1" but fills the allocated memory with zeros
590
591       allocnz
592           Same as "allocn" but fills the allocated memory with zeros
593
594       prima_mallocz
595           Same as malloc() but fills the allocated memory with zeros
596
597       prima_hash_create
598            PHash(void)
599
600           Creates an empty hash
601
602       prima_hash_destroy
603            void(PHash self, Bool killAll);
604
605           Destroys a hash. If killAll is true, assumes that every value in
606           the hash is a dynamic memory pointer and calls free() on each.
607
608       prima_hash_fetch
609            void*( PHash self, const void *key, int keyLen);
610
611           Returns pointer to a value, if found, nil otherwise
612
613       prima_hash_delete
614            void*( PHash self, const void *key, int keyLen, Bool kill);
615
616           Deletes hash key and returns associated value.  if kill is true,
617           calls free() on the value and returns nil.
618
619       prima_hash_store
620            void( PHash self, const void *key, int keyLen, void *val);
621
622           Stores new value into hash. If the key is already present, old
623           value is overwritten.
624
625       prima_hash_count
626            int(PHash self)
627
628           Returns number of keys in the hash
629
630       prima_hash_first_that
631            void * ( PHash self, void *action, void *params, int *pKeyLen, void **pKey);
632
633           Enumerates all hash entries, calling action procedure on each.  If
634           the action procedure returns true, enumeration stops and the last
635           processed value is returned. Otherwise nil is returned. action have
636           to be function declared as
637
638            Bool action_callback( void * value, int keyLen, void * key, void * params);
639
640           params is a pointer to an arbitrary user data
641
642       kind_of
643            Bool( Handle object, void *cls);
644
645           Returns true, if the object is an exemplar of class cls or its
646           descendant
647
648       PERL_CALL_METHOD, PERL_CALL_PV
649           To be used instead of perl_call_method and perl_call_pv, described
650           in perlguts manpage. These functions aliased to a code with the
651           workaround of perl bug which emerges when G_EVAL flag is combined
652           with G_SCALAR.
653
654       eval
655            SV *( char *string)
656
657           Simplified perl_eval_pv() call.
658
659       sv_query_method
660            CV * ( SV * object, char *methodName, Bool cacheIt);
661
662           Returns perl pointer to a method searched by a scalar and a name If
663           cacheIt true, caches the hierarchy traverse result for a speedup.
664
665       query_method
666            CV * ( Handle object, char *methodName, Bool cacheIt);
667
668           Returns perl pointer to a method searched by an object and a name
669           If cacheIt true, caches the hierarchy traverse result for a
670           speedup.
671
672       call_perl_indirect
673            SV * ( Handle self, char *subName, const char *format, Bool cdecl,
674                   Bool coderef, va_list params);
675
676           Core function for calling Prima methods. Is used by the following
677           three functions, but is never called directly. Format is described
678           in "Calling perl code" section.
679
680       call_perl
681            SV * ( Handle self, char *subName, const char *format, ...);
682
683           Calls method of an object pointer by a Handle
684
685       sv_call_perl
686            SV * ( SV * mate, char *subName, const char *format, ...);
687
688           Calls method of an object pointed by a SV*
689
690       cv_call_perl
691            SV * ( SV * mate, Sv * coderef, const char *format, ...);
692
693           Calls arbitrary perl code with mate as first parameter.  Used in
694           notifications mechanism.
695
696       Object_create
697            Handle( char * className, HV * profile);
698
699           Creates an exemplar of className class with parameters in profile.
700           Never returns nilHandle, throws an exception instead.
701
702       create_object
703            void*( const char *objClass, const char *format, ...);
704
705           Convenience wrapper to Object_create. Uses format specification
706           that is described in "Calling perl code".
707
708       create_instance
709            Handle( const char * className)
710
711           Convenience call to "Object_create" with parameters in hash
712           'profile'.
713
714       Object_destroy
715            void( Handle self);
716
717           Destroys object. One of few Prima function that can be called in
718           re-entrant fashion.
719
720       Object_alive
721            void( Handle self);
722
723           Returns non-zero is object is alive, 0 otherwise.  In particular,
724           current implementation returns 1 if object's stage is csNormal and
725           2 if it is csConstructing.  Has virtually no use in C, only used in
726           perl code.
727
728       protect_object
729            void( Handle obj);
730
731           restricts object pointer from deletion after Object_destroy().  Can
732           be called several times on an object.  Increments Object.
733           protectCount.
734
735       unprotect_object
736            void( Handle obj);
737
738           Frees object pointer after Object. protectCount hits zero.  Can be
739           called several times on an object.
740
741       parse_hv
742            HV *( I32 ax, SV **sp, I32 items, SV **mark, int expected, const char *methodName);
743
744           Transfers arguments in perl stack to a newly created HV and returns
745           it.
746
747       push_hv
748            void ( I32 ax, SV **sp, I32 items, SV **mark, int callerReturns, HV *hv);
749
750           Puts all hv contents back to perl stack.
751
752       push_hv_for_REDEFINED
753            SV **( SV **sp, HV *hv);
754
755           Puts hv content as arguments to perl code to be called
756
757       pop_hv_for_REDEFINED
758            int ( SV **sp, int count, HV *hv, int shouldBe);
759
760           Reads result of executed perl code and stores them into hv.
761
762       pexist
763            Bool(char*key)
764
765           Return true if a key is present into hash 'profile'
766
767       pdelete
768            void(char*key)
769
770           Deletes a key in hash 'profile'
771
772       pget_sv, pget_i, pget_f, pget_c, pget_H, pget_B
773            TYPE(char*key)
774
775           Returns value of ( SV*, int, float, char*, Handle or Bool) that is
776           associated to a key in hash 'profile'. Calls croak() if the key is
777           not present.
778
779       pset_sv, pset_i, pset_f, pset_c, pset_H
780            void( char*key, TYPE value)
781
782           Assigns a value to a key in hash 'profile' and increments reference
783           count to a newly created scalar.
784
785       pset_b
786            void( char*key, void* data, int length)
787
788           Assigns binary data to a key in hash 'profile' and increments
789           reference count to a newly created scalar.
790
791       pset_sv_noinc
792            void(char* key, SV * sv)
793
794           Assigns scalar value to a key  in hash 'profile' without reference
795           count increment.
796
797       duplicate_string
798            char*( const char *)
799
800           Returns copy of a string
801
802       list_create
803            void ( PList self, int size, int delta);
804
805           Creates a list instance with a static List structure.
806
807       plist_create
808            PList( int size, int delta);
809
810           Created list instance and returns newly allocated List structure.
811
812       list_destroy
813            void( PList self);
814
815           Destroys list data.
816
817       plist_destroy
818            void ( PList self);
819
820           Destroys list data and frees list instance.
821
822       list_add
823            int( PList self, Handle item);
824
825           Adds new item into a list, returns its index or -1 on error.
826
827       list_insert_at
828            int ( PList self, Handle item, int pos);
829
830           Inserts new item into a list at a given position, returns its
831           position or -1 on error.
832
833       list_at
834            Handle ( PList self, int index);
835
836           Returns items that is located at given index or nilHandle if the
837           index is out of range.
838
839       list_delete
840            void( PList self, Handle item);
841
842           Removes the item from list.
843
844       list_delete_at
845            void( PList self, int index);
846
847           Removes the item located at given index from a list.
848
849       list_delete_all
850            void ( PList self, Bool kill);
851
852           Removes all items from the list. If kill is true, calls free() on
853           every item before.
854
855       list_first_that
856            int( PList self, void * action, void * params);
857
858           Enumerates all list entries, calling action procedure on each.  If
859           action returns true, enumeration stops and the index is returned.
860           Otherwise -1 is returned. action have to be a function declared as
861
862            Bool action_callback( Handle item, void * params);
863
864           params is a pointer to an arbitrary user data
865
866       list_index_of
867            int( PList self, Handle item);
868
869           Returns index of an item, or -1 if the item is not in the list.
870

AUTHOR

872       Dmitry Karasik, <dmitry@karasik.eu.org>.
873

SEE ALSO

875       Prima
876
877
878
879perl v5.32.1                      2021-01-27          pod::Prima::internals(3)
Impressum