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 banded 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 overridable.
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       or even
188
189          create_object("SampleObject", "si",
190              "name", "Sample",
191              "index", 10
192          );
193
194       Convenience pset_XX macros assign a value of XX type to the hash key
195       given as a first parameter, to a hash variable named profile. "pset_i"
196       works with integers, "pset_c" - with strings, etc.
197
198   Destruction
199       As well as create() method, every object class has destroy() method.
200       Object can be destroyed either from perl
201
202          $obj-> destroy
203
204       or from C
205
206          Object_destroy( obj);
207
208       An object can be automatically destroyed when its reference count
209       reaches 0. Note that the auto destruction would never happen if the
210       object's reference count is not lowered after its creation. The code
211
212          --SvREFCNT( SvRV( PAnyObject(object)-> mate));
213
214       is required if the object is to be returned to perl.  If that code is
215       not called, the object still could be destroyed explicitly, but its
216       reference would still live, resulting in memory leak problem.
217
218       For user code it is sufficient to overload done() and/or cleanup()
219       methods, or just onDestroy notifications. It is highly recommended to
220       avoid overloading destroy method, since it can be called in re-entrant
221       fashion. When overloading done(), be prepared that it may be called
222       inside init(), and deal with the semi-initialized object.
223
224   Data instance
225       All object data after their creation represent an object instance.  All
226       Prima objects are blessed hashes, and the hash key __CMATE__ holds a C
227       pointer to a memory which is occupied by C data instance, or a "mate".
228       It keeps all object variables and a pointer to VMT. Every object has
229       its own copy of data instance, but the VMTs can be shared. In order to
230       reach to C data instance gimme_the_mate() function is used. As a first
231       parameter it accepts a scalar (SV*), which is expected to be a
232       reference to a hash, and returns the C data instance if the scalar is a
233       Prima object.
234
235   Object life stages
236       It was decided to divide object life stage in several steps.  Every
237       stage is mirrored into PObject(self)-> stage integer variable, which
238       can be one of csXXX constants.  Currently it has six:
239
240       csConstructing
241           Initial stage, is set until create() is finished.  Right after
242           init() is completed, setup() method is called.
243
244       csNormal
245           After create() is finished and before destroy() started.  If an
246           object is csNormal and csConstructing stage, Object_alive() result
247           would be non-zero.
248
249       csDestroying
250           destroy() started. This stage includes calling of cleanup() and
251           done() routines.
252
253       csFrozen
254           cleanup() started.
255
256       csFinalizing
257           done() started
258
259       csDead
260           Destroy finished
261

Coding techniques

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

API reference

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

AUTHOR

879       Dmitry Karasik, <dmitry@karasik.eu.org>.
880

SEE ALSO

882       Prima
883
884
885
886perl v5.36.0                      2023-03-20          pod::Prima::internals(3)
Impressum