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 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 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 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 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 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 Destruction
192 As well as create() method, every object class has destroy() method.
193 Object can be destroyed either from perl
194 $obj-> destroy
196 or from C
198 Object_destroy( obj);
200 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 --SvREFCNT( SvRV( PAnyObject(object)-> mate));
206 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 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 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 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 csConstructing
234 Initial stage, is set until create() is finished. Right after
235 init() is completed, setup() method is called.
236 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 csDestroying
243 destroy() started. This stage includes calling of cleanup() and
244 done() routines.
245 csFrozen
247 cleanup() started.
248 csFinalizing
250 done() started
251 csDead
253 Destroy finished
254
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 ((PComponent) self)-> name; // classic C
263 PComponent(self)-> name; // using PComponent() macro from apricot.h
264 var-> name; // using local var() macro
265 Object code could to be called also in several ways:
267 (((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 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 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 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 each character of format string represents a parameters type, and
286 characters can be:
287 'i' - integer
289 's' - char *
290 'n' - float
291 'H' - Handle
292 'S' - SV *
293 'P' - Point
294 'R' - Rect
295 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 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 SvTRUE( GvSV( errgv))
307 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 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 This technique provides workaround to a "false alarm" situation, if
328 SvTRUE( GvSV( errgv)) is true before perl_call_method().
329 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 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 function( Handle object) {
343 int stage;
344 protect_object( object);
345 // call some perl code
347 perl_call_method( object, "test", ...);
348 stage = PObject(object)-> stage;
350 unprotect_object( object);
351 if ( stage == csDead) return;
352 // proceed with the object
354 }
355 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 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 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 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 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 static
392 Handle xdup( Handle self, char * className)
393 {
394 Handle h;
395 Point s;
396 PDrawable i;
397 // allocate a parameters hash
399 HV * profile = newHV();
400 // 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 // create object
408 h = Object_create( className, profile);
409 // free profile, do not need it anymore
411 sv_free(( SV *) profile);
412 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 // decrement reference count
420 --SvREFCNT( SvRV( i-> mate));
421 return h;
422 }
423 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 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 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 Thus
441 $c = Prima::Object-> create();
443 and
445 Prima::Object-> create;
446 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 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 Component_notify( self, "<sH", "Paint", self);
467 Component_notify( self, "<sPii", "MouseDown", self, point, int, int);
468 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 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 $c-> set( index => 10, name => "Sample" );
479 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 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 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 $image-> type( $a);
513 $image-> palette( $b);
514 and
516 $image-> palette( $b);
518 $image-> type( $a);
519 produce different results. Therefore it might be only solution to code
521 Class_set() explicitly.
522 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 $image-> set(
528 owner => $xxx,
529 type => 24,
530 __ORDER__ => [qw( type owner)],
531 );
532
534 Variables
535 primaObjects, PHash
536 Hash with all prima objects, where keys are their data instances
537 application, Handle
539 Pointer to an application. There can be only one Application
540 instance at a time, or none at all.
541 Macros and functions
543 dG_EVAL_ARGS
544 Defines variable for $@ value storage
545 OPEN_G_EVAL, CLOSE_G_EVAL
547 Brackets for exception catching
548 build_static_vmt
550 Bool(void * vmt)
551 Caches pre-built VMT for further use
553 build_dynamic_vmt
555 Bool( void * vmt, char * ancestorName, int ancestorVmtSize)
556 Creates a subclass from vmt and caches result under ancestorName
558 key
559 gimme_the_vmt
561 PVMT( const char *className);
562 Returns VMT pointer associated with class by name.
564 gimme_the_mate
566 Handle( SV * perlObject)
567 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 gimme_the_real_mate
572 Handle( SV * perlObject)
573 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 alloc1
579 alloc1(type)
580 To be used instead (type*)(malloc(sizeof(type))
582 allocn
584 allocn(type,n)
585 To be used instead (type*)(malloc((n)*sizeof(type))
587 alloc1z
589 Same as "alloc1" but fills the allocated memory with zeros
590 allocnz
592 Same as "allocn" but fills the allocated memory with zeros
593 prima_mallocz
595 Same as malloc() but fills the allocated memory with zeros
596 prima_hash_create
598 PHash(void)
599 Creates an empty hash
601 prima_hash_destroy
603 void(PHash self, Bool killAll);
604 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 prima_hash_fetch
609 void*( PHash self, const void *key, int keyLen);
610 Returns pointer to a value, if found, nil otherwise
612 prima_hash_delete
614 void*( PHash self, const void *key, int keyLen, Bool kill);
615 Deletes hash key and returns associated value. if kill is true,
617 calls free() on the value and returns nil.
618 prima_hash_store
620 void( PHash self, const void *key, int keyLen, void *val);
621 Stores new value into hash. If the key is already present, old
623 value is overwritten.
624 prima_hash_count
626 int(PHash self)
627 Returns number of keys in the hash
629 prima_hash_first_that
631 void * ( PHash self, void *action, void *params, int *pKeyLen, void **pKey);
632 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 Bool action_callback( void * value, int keyLen, void * key, void * params);
639 params is a pointer to an arbitrary user data
641 kind_of
643 Bool( Handle object, void *cls);
644 Returns true, if the object is an exemplar of class cls or its
646 descendant
647 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 eval
655 SV *( char *string)
656 Simplified perl_eval_pv() call.
658 sv_query_method
660 CV * ( SV * object, char *methodName, Bool cacheIt);
661 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 query_method
666 CV * ( Handle object, char *methodName, Bool cacheIt);
667 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 call_perl_indirect
673 SV * ( Handle self, char *subName, const char *format, Bool cdecl,
674 Bool coderef, va_list params);
675 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 call_perl
681 SV * ( Handle self, char *subName, const char *format, ...);
682 Calls method of an object pointer by a Handle
684 sv_call_perl
686 SV * ( SV * mate, char *subName, const char *format, ...);
687 Calls method of an object pointed by a SV*
689 cv_call_perl
691 SV * ( SV * mate, Sv * coderef, const char *format, ...);
692 Calls arbitrary perl code with mate as first parameter. Used in
694 notifications mechanism.
695 Object_create
697 Handle( char * className, HV * profile);
698 Creates an exemplar of className class with parameters in profile.
700 Never returns nilHandle, throws an exception instead.
701 create_object
703 void*( const char *objClass, const char *format, ...);
704 Convenience wrapper to Object_create. Uses format specification
706 that is described in "Calling perl code".
707 create_instance
709 Handle( const char * className)
710 Convenience call to "Object_create" with parameters in hash
712 'profile'.
713 Object_destroy
715 void( Handle self);
716 Destroys object. One of few Prima function that can be called in
718 re-entrant fashion.
719 Object_alive
721 void( Handle self);
722 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 protect_object
729 void( Handle obj);
730 restricts object pointer from deletion after Object_destroy(). Can
732 be called several times on an object. Increments Object.
733 protectCount.
734 unprotect_object
736 void( Handle obj);
737 Frees object pointer after Object. protectCount hits zero. Can be
739 called several times on an object.
740 parse_hv
742 HV *( I32 ax, SV **sp, I32 items, SV **mark, int expected, const char *methodName);
743 Transfers arguments in perl stack to a newly created HV and returns
745 it.
746 push_hv
748 void ( I32 ax, SV **sp, I32 items, SV **mark, int callerReturns, HV *hv);
749 Puts all hv contents back to perl stack.
751 push_hv_for_REDEFINED
753 SV **( SV **sp, HV *hv);
754 Puts hv content as arguments to perl code to be called
756 pop_hv_for_REDEFINED
758 int ( SV **sp, int count, HV *hv, int shouldBe);
759 Reads result of executed perl code and stores them into hv.
761 pexist
763 Bool(char*key)
764 Return true if a key is present into hash 'profile'
766 pdelete
768 void(char*key)
769 Deletes a key in hash 'profile'
771 pget_sv, pget_i, pget_f, pget_c, pget_H, pget_B
773 TYPE(char*key)
774 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 pset_sv, pset_i, pset_f, pset_c, pset_H
780 void( char*key, TYPE value)
781 Assigns a value to a key in hash 'profile' and increments reference
783 count to a newly created scalar.
784 pset_b
786 void( char*key, void* data, int length)
787 Assigns binary data to a key in hash 'profile' and increments
789 reference count to a newly created scalar.
790 pset_sv_noinc
792 void(char* key, SV * sv)
793 Assigns scalar value to a key in hash 'profile' without reference
795 count increment.
796 duplicate_string
798 char*( const char *)
799 Returns copy of a string
801 list_create
803 void ( PList self, int size, int delta);
804 Creates a list instance with a static List structure.
806 plist_create
808 PList( int size, int delta);
809 Created list instance and returns newly allocated List structure.
811 list_destroy
813 void( PList self);
814 Destroys list data.
816 plist_destroy
818 void ( PList self);
819 Destroys list data and frees list instance.
821 list_add
823 int( PList self, Handle item);
824 Adds new item into a list, returns its index or -1 on error.
826 list_insert_at
828 int ( PList self, Handle item, int pos);
829 Inserts new item into a list at a given position, returns its
831 position or -1 on error.
832 list_at
834 Handle ( PList self, int index);
835 Returns items that is located at given index or nilHandle if the
837 index is out of range.
838 list_delete
840 void( PList self, Handle item);
841 Removes the item from list.
843 list_delete_at
845 void( PList self, int index);
846 Removes the item located at given index from a list.
848 list_delete_all
850 void ( PList self, Bool kill);
851 Removes all items from the list. If kill is true, calls free() on
853 every item before.
854 list_first_that
856 int( PList self, void * action, void * params);
857 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 Bool action_callback( Handle item, void * params);
863 params is a pointer to an arbitrary user data
865 list_index_of
867 int( PList self, Handle item);
868 Returns index of an item, or -1 if the item is not in the list.
870
872 Dmitry Karasik, <dmitry@karasik.eu.org>.
873
875 Prima
876perl v5.32.1 2021-01-27 pod::Prima::internals(3)