1pod::Prima::internals(3U)ser Contributed Perl Documentatipoond::Prima::internals(3)
2
6 Prima::internals - Prima internal architecture
7
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
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 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 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 Const.pm:
50 package fe; *AUTOLOAD = \&Prima::Const::AUTOLOAD;
51 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
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 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 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 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 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 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 newXS( "Prima::Class::init", Class_init_FROMPERL, "Prima::Class");
95 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 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 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 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 Built-in classes
123 Prima defines the following built-in classes: (in hierarchy order)
124 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 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
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 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 Objects can be created from perl by using following code example:
172 $obj = Prima::SampleObject-> create(
174 name => "Sample",
175 index => 10,
176 );
177 and from C:
179 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 or even
188 create_object("SampleObject", "si",
190 "name", "Sample",
191 "index", 10
192 );
193 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 Destruction
199 As well as create() method, every object class has destroy() method.
200 Object can be destroyed either from perl
201 $obj-> destroy
203 or from C
205 Object_destroy( obj);
207 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 --SvREFCNT( SvRV( PAnyObject(object)-> mate));
213 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 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 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 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 csConstructing
241 Initial stage, is set until create() is finished. Right after
242 init() is completed, setup() method is called.
243 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 csDestroying
250 destroy() started. This stage includes calling of cleanup() and
251 done() routines.
252 csFrozen
254 cleanup() started.
255 csFinalizing
257 done() started
258 csDead
260 Destroy finished
261
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 ((PComponent) self)-> name; // classic C
270 PComponent(self)-> name; // using PComponent() macro from apricot.h
271 var-> name; // using local var() macro
272 Object code could to be called also in several ways:
274 (((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 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 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 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 each character of format string represents a parameters type, and
293 characters can be:
294 'i' - integer
296 's' - char *
297 'n' - float
298 'H' - Handle
299 'S' - SV *
300 'P' - Point
301 'R' - Rect
302 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 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 SvTRUE( GvSV( errgv))
314 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 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 This technique provides workaround to a "false alarm" situation, if
335 SvTRUE( GvSV( errgv)) is true before perl_call_method().
336 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 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 function( Handle object) {
350 int stage;
351 protect_object( object);
352 // call some perl code
354 perl_call_method( object, "test", ...);
355 stage = PObject(object)-> stage;
357 unprotect_object( object);
358 if ( stage == csDead) return;
359 // proceed with the object
361 }
362 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 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 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 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 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 static
399 Handle xdup( Handle self, char * className)
400 {
401 Handle h;
402 Point s;
403 PDrawable i;
404 // allocate a parameters hash
406 HV * profile = newHV();
407 // 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 // create object
415 h = Object_create( className, profile);
416 // free profile, do not need it anymore
418 sv_free(( SV *) profile);
419 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 // decrement reference count
427 --SvREFCNT( SvRV( i-> mate));
428 return h;
429 }
430 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 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 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 Thus
448 $c = Prima::Object-> create();
450 and
452 Prima::Object-> create;
453 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 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 Component_notify( self, "<sH", "Paint", self);
474 Component_notify( self, "<sPii", "MouseDown", self, point, int, int);
475 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 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 $c-> set( index => 10, name => "Sample" );
486 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 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 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 $image-> type( $a);
520 $image-> palette( $b);
521 and
523 $image-> palette( $b);
525 $image-> type( $a);
526 produce different results. Therefore it might be only solution to code
528 Class_set() explicitly.
529 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 $image-> set(
535 owner => $xxx,
536 type => 24,
537 __ORDER__ => [qw( type owner)],
538 );
539
541 Variables
542 primaObjects, PHash
543 Hash with all prima objects, where keys are their data instances
544 application, Handle
546 Pointer to an application. There can be only one Application
547 instance at a time, or none at all.
548 Macros and functions
550 dG_EVAL_ARGS
551 Defines variable for $@ value storage
552 OPEN_G_EVAL, CLOSE_G_EVAL
554 Brackets for exception catching
555 build_static_vmt
557 Bool(void * vmt)
558 Caches pre-built VMT for further use
560 build_dynamic_vmt
562 Bool( void * vmt, char * ancestorName, int ancestorVmtSize)
563 Creates a subclass from vmt and caches result under ancestorName
565 key
566 gimme_the_vmt
568 PVMT( const char *className);
569 Returns VMT pointer associated with class by name.
571 gimme_the_mate
573 Handle( SV * perlObject)
574 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 gimme_the_real_mate
579 Handle( SV * perlObject)
580 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 alloc1
586 alloc1(type)
587 To be used instead (type*)(malloc(sizeof(type))
589 allocn
591 allocn(type,n)
592 To be used instead (type*)(malloc((n)*sizeof(type))
594 alloc1z
596 Same as "alloc1" but fills the allocated memory with zeros
597 allocnz
599 Same as "allocn" but fills the allocated memory with zeros
600 prima_mallocz
602 Same as malloc() but fills the allocated memory with zeros
603 prima_hash_create
605 PHash(void)
606 Creates an empty hash
608 prima_hash_destroy
610 void(PHash self, Bool killAll);
611 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 prima_hash_fetch
616 void*( PHash self, const void *key, int keyLen);
617 Returns pointer to a value, if found, nil otherwise
619 prima_hash_delete
621 void*( PHash self, const void *key, int keyLen, Bool kill);
622 Deletes hash key and returns associated value. if kill is true,
624 calls free() on the value and returns nil.
625 prima_hash_store
627 void( PHash self, const void *key, int keyLen, void *val);
628 Stores new value into hash. If the key is already present, old
630 value is overwritten.
631 prima_hash_count
633 int(PHash self)
634 Returns number of keys in the hash
636 prima_hash_first_that
638 void * ( PHash self, void *action, void *params, int *pKeyLen, void **pKey);
639 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 Bool action_callback( void * value, int keyLen, void * key, void * params);
646 params is a pointer to an arbitrary user data
648 kind_of
650 Bool( Handle object, void *cls);
651 Returns true, if the object is an exemplar of class cls or its
653 descendant
654 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 eval
662 SV *( char *string)
663 Simplified perl_eval_pv() call.
665 sv_query_method
667 CV * ( SV * object, char *methodName, Bool cacheIt);
668 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 query_method
673 CV * ( Handle object, char *methodName, Bool cacheIt);
674 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 call_perl_indirect
680 SV * ( Handle self, char *subName, const char *format, Bool cdecl,
681 Bool coderef, va_list params);
682 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 call_perl
688 SV * ( Handle self, char *subName, const char *format, ...);
689 Calls method of an object pointer by a Handle
691 sv_call_perl
693 SV * ( SV * mate, char *subName, const char *format, ...);
694 Calls method of an object pointed by a SV*
696 cv_call_perl
698 SV * ( SV * mate, Sv * coderef, const char *format, ...);
699 Calls arbitrary perl code with mate as first parameter. Used in
701 notifications mechanism.
702 Object_create
704 Handle( char * className, HV * profile);
705 Creates an exemplar of className class with parameters in profile.
707 Never returns NULL_HANDLE, throws an exception instead.
708 create_object
710 void*( const char *objClass, const char *format, ...);
711 Convenience wrapper to Object_create. Uses format specification
713 that is described in "Calling perl code".
714 create_instance
716 Handle( const char * className)
717 Convenience call to "Object_create" with parameters in hash
719 'profile'.
720 Object_destroy
722 void( Handle self);
723 Destroys object. One of few Prima function that can be called in
725 re-entrant fashion.
726 Object_alive
728 void( Handle self);
729 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 protect_object
736 void( Handle obj);
737 restricts object pointer from deletion after Object_destroy(). Can
739 be called several times on an object. Increments Object.
740 protectCount.
741 unprotect_object
743 void( Handle obj);
744 Frees object pointer after Object. protectCount hits zero. Can be
746 called several times on an object.
747 parse_hv
749 HV *( I32 ax, SV **sp, I32 items, SV **mark, int expected, const char *methodName);
750 Transfers arguments in perl stack to a newly created HV and returns
752 it.
753 push_hv
755 void ( I32 ax, SV **sp, I32 items, SV **mark, int callerReturns, HV *hv);
756 Puts all hv contents back to perl stack.
758 push_hv_for_REDEFINED
760 SV **( SV **sp, HV *hv);
761 Puts hv content as arguments to perl code to be called
763 pop_hv_for_REDEFINED
765 int ( SV **sp, int count, HV *hv, int shouldBe);
766 Reads result of executed perl code and stores them into hv.
768 pexist
770 Bool(char*key)
771 Return true if a key is present into hash 'profile'
773 pdelete
775 void(char*key)
776 Deletes a key in hash 'profile'
778 pget_sv, pget_i, pget_f, pget_c, pget_H, pget_B
780 TYPE(char*key)
781 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 pset_sv, pset_i, pset_f, pset_c, pset_H
787 void( char*key, TYPE value)
788 Assigns a value to a key in hash 'profile' and increments reference
790 count to a newly created scalar.
791 pset_b
793 void( char*key, void* data, int length)
794 Assigns binary data to a key in hash 'profile' and increments
796 reference count to a newly created scalar.
797 pset_sv_noinc
799 void(char* key, SV * sv)
800 Assigns scalar value to a key in hash 'profile' without reference
802 count increment.
803 duplicate_string
805 char*( const char *)
806 Returns copy of a string
808 list_create
810 void ( PList self, int size, int delta);
811 Creates a list instance with a static List structure.
813 plist_create
815 PList( int size, int delta);
816 Created list instance and returns newly allocated List structure.
818 list_destroy
820 void( PList self);
821 Destroys list data.
823 plist_destroy
825 void ( PList self);
826 Destroys list data and frees list instance.
828 list_add
830 int( PList self, Handle item);
831 Adds new item into a list, returns its index or -1 on error.
833 list_insert_at
835 int ( PList self, Handle item, int pos);
836 Inserts new item into a list at a given position, returns its
838 position or -1 on error.
839 list_at
841 Handle ( PList self, int index);
842 Returns items that is located at given index or NULL_HANDLE if the
844 index is out of range.
845 list_delete
847 void( PList self, Handle item);
848 Removes the item from list.
850 list_delete_at
852 void( PList self, int index);
853 Removes the item located at given index from a list.
855 list_delete_all
857 void ( PList self, Bool kill);
858 Removes all items from the list. If kill is true, calls free() on
860 every item before.
861 list_first_that
863 int( PList self, void * action, void * params);
864 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 Bool action_callback( Handle item, void * params);
870 params is a pointer to an arbitrary user data
872 list_index_of
874 int( PList self, Handle item);
875 Returns index of an item, or -1 if the item is not in the list.
877
879 Dmitry Karasik, <dmitry@karasik.eu.org>.
880
882 Prima
883perl v5.36.0 2023-03-20 pod::Prima::internals(3)