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 Timer
139 Widget
140 Application
141 Window
142 These classes can be seen from perl with Prima:: prefix. Along with
144 these, Utils class is defined. Its only difference is that it cannot be
145 used as a prototype for an object, and used merely as a package that
146 binds functions. Classes that are not intended to be an object
147 prototype marked with 'package' prefix, when others are marked with
148 'object' (see prima-gencls manpage).
149
151 This chapter deals only with Prima::Object descendants, pure perl
152 objects are not of interest here, so the 'object' term is thereafter
153 referenced to Prima::Object descendant object. Prima employs blessed
154 hashes for its objects.
155 Creation
157 All built-in object classes and their descendants can be used for
158 creating objects with perl semantics. Perl objects are created by
159 calling bless(), but it is not enough to create Prima objects. Every
160 Prima::Object descendant class therefore is equipped with create()
161 method, that allocates object instance and calls bless() itself.
162 Parameters that come with create() call are formed into a hash and
163 passed to init() method, that is also present on every object. Note the
164 fact that although perl-coded init() returns the hash, it not seen in C
165 code. This is a special consideration for the methods that have 'HV *
166 profile' as a last parameter in their class declaration. The
167 corresponding thunk copies the hash content back to perl stack, using
168 parse_hv() and push_hv() functions.
169 Objects can be created from perl by using following code example:
171 $obj = Prima::SampleObject-> create(
173 name => "Sample",
174 index => 10,
175 );
176 and from C:
178 Handle obj;
180 HV * profile = newHV();
181 pset_c( name, "Sample");
182 pset_i( index, 10);
183 obj = Object_create("SampleObject", profile);
184 sv_free(( SV*) profile);
185 Convenience pset_XX macros assign a value of XX type to the hash key
187 given as a first parameter, to a hash variable named profile. "pset_i"
188 works with integers, "pset_c" - with strings, etc.
189 Destruction
191 As well as create() method, every object class has destroy() method.
192 Object can be destroyed either from perl
193 $obj-> destroy
195 or from C
197 Object_destroy( obj);
199 An object can be automatically destroyed when its reference count
201 reaches 0. Note that the auto destruction would never happen if the
202 object's reference count is not lowered after its creation. The code
203 --SvREFCNT( SvRV( PAnyObject(object)-> mate));
205 is required if the object is to be returned to perl. If that code is
207 not called, the object still could be destroyed explicitly, but its
208 reference would still live, resulting in memory leak problem.
209 For user code it is sufficient to overload done() and/or cleanup()
211 methods, or just onDestroy notifications. It is highly recommended to
212 avoid overloading destroy method, since it can be called in re-entrant
213 fashion. When overloading done(), be prepared that it may be called
214 inside init(), and deal with the semi-initialized object.
215 Data instance
217 All object data after their creation represent an object instance. All
218 Prima objects are blessed hashes, and the hash key __CMATE__ holds a C
219 pointer to a memory which is occupied by C data instance, or a "mate".
220 It keeps all object variables and a pointer to VMT. Every object has
221 its own copy of data instance, but the VMTs can be shared. In order to
222 reach to C data instance gimme_the_mate() function is used. As a first
223 parameter it accepts a scalar (SV*), which is expected to be a
224 reference to a hash, and returns the C data instance if the scalar is a
225 Prima object.
226 Object life stages
228 It was decided to divide object life stage in several steps. Every
229 stage is mirrored into PObject(self)-> stage integer variable, which
230 can be one of csXXX constants. Currently it has six:
231 csConstructing
233 Initial stage, is set until create() is finished. Right after
234 init() is completed, setup() method is called.
235 csNormal
237 After create() is finished and before destroy() started. If an
238 object is csNormal and csConstructing stage, Object_alive() result
239 would be non-zero.
240 csDestroying
242 destroy() started. This stage includes calling of cleanup() and
243 done() routines.
244 csFrozen
246 cleanup() started.
247 csFinalizing
249 done() started
250 csDead
252 Destroy finished
253
255 Accessing object data
256 C coding has no specific conventions, except when a code is an object
257 method. Object syntax for accessing object instance data is also fairly
258 standard. For example, accessing component's field called 'name' can
259 be done in several ways:
260 ((PComponent) self)-> name; // classic C
262 PComponent(self)-> name; // using PComponent() macro from apricot.h
263 var-> name; // using local var() macro
264 Object code could to be called also in several ways:
266 (((PComponent) self)-> self)-> get_name( self); // classic C
268 CComponent(self)-> get_name( self); // using CComponent() macro from apricot.h
269 my-> get_name( self); // using local my() macro
270 This calling is preferred, comparing to direct call of
272 Component_get_name(), primarily because get_name() is a method and can
273 be overridden from user code.
274 Calling perl code
276 call_perl_indirect() function accepts object, its method name and
277 parameters list with parameter format string. It has several wrappers
278 for easier use, which are:
279 call_perl( Handle self, char * method, char * format, ...)
281 sv_call_perl( SV * object, char * method, char * format, ...)
282 cv_call_perl( SV * object, SV * code_reference, char * format, ...)
283 each character of format string represents a parameters type, and
285 characters can be:
286 'i' - integer
288 's' - char *
289 'n' - float
290 'H' - Handle
291 'S' - SV *
292 'P' - Point
293 'R' - Rect
294 The format string can be prepended with '<' character, in which case SV
296 * scalar ( always scalar, even if code returns nothing or array ) value
297 is returned. The caller is responsible for freeing the return value.
298 Exceptions
300 As descriped in perlguts manpage, G_EVAL flag is used in perl_call_sv()
301 and perl_call_method() to indicate that an eventual exception should
302 never be propagated automatically. The caller checks if the exception
303 was taken place by evaluating
304 SvTRUE( GvSV( errgv))
306 statement. It is guaranteed to be false if there was no exception
308 condition. But in some situations, namely, when no perl_call_*
309 functions are called or error value is already assigned before calling
310 code, there is a wrapping technique that keeps previous error message
311 and looks like:
312 dG_EVAL_ARGS; // define arguments
314 ....
315 OPEN_G_EVAL; // open brackets
316 // call code
317 perl_call_method( ... | G_EVAL); // G_EVAL is necessary
318 if ( SvTRUE( GvSV( errgv)) {
319 CLOSE_G_EVAL; // close brackets
320 croak( SvPV_nolen( GvSV( errgv)));// propagate exception
321 // no code is executed after croak
322 }
323 CLOSE_G_EVAL; // close brackets
324 ...
325 This technique provides workaround to a "false alarm" situation, if
327 SvTRUE( GvSV( errgv)) is true before perl_call_method().
328 Object protection
330 After the object destroy stage is completed, it is possible that
331 object's data instance is gone, and even simple stage check might cause
332 segmentation fault. To avoid this, bracketing functions called
333 "protect_object()" and "unprotect_object()" are used. protect_object()
334 increments reference count to the object instance, thus delaying its
335 freeing until decrementing unprotect_object() is called.
336 All C code that references to an object must check for its stage after
338 every routine that switches to perl code, because the object might be
339 destroyed inside the call. Typical code example would be like:
340 function( Handle object) {
342 int stage;
343 protect_object( object);
344 // call some perl code
346 perl_call_method( object, "test", ...);
347 stage = PObject(object)-> stage;
349 unprotect_object( object);
350 if ( stage == csDead) return;
351 // proceed with the object
353 }
354 Usual C code never checks for object stage before the call, because
356 gimme_the_mate() function returns NULL if object's stage is csDead, and
357 majority of Prima C code is prepended with this call, thus rejecting
358 invalid references on early stage. If it is desired to get the C mate
359 for objects that are in csDead stage, use "gimme_the_real_mate()"
360 function instead.
361 init
363 Object's method init() is responsible for setting all its initial
364 properties to the object, but all code that is executed inside init
365 must be aware that the object's stage is csConstructing. init()
366 consists of two parts: calling of ancestor's init() and setting
367 properties. Examples are many in both C and perl code, but in short it
368 looks like:
369 void
371 Class_init( Handle self, HV * profile)
372 {
373 inherited init( self, profile);
374 my-> set_index( pget_i( index));
375 my-> set_name( pget_c( name));
376 }
377 pget_XX macros call croak() if the profile key is not present into
379 profile, but the mechanism guarantees that all keys that are listed in
380 profile_default() are conveyed to init(). For explicit checking of key
381 presence pexists() macro is used, and pdelete() is used for key
382 deletion, although is it not recommended to use pdelete() inside
383 init().
384 Object creation and returning
386 As described is previous sections, there are some precautions to be
387 taken into account when an object is created inside C code. A piece of
388 real code from DeviceBitmap.c would serve as an example:
389 static
391 Handle xdup( Handle self, char * className)
392 {
393 Handle h;
394 Point s;
395 PDrawable i;
396 // allocate a parameters hash
398 HV * profile = newHV();
399 // set all necessary arguments
401 pset_H( owner, var-> owner);
402 pset_i( width, var-> w);
403 pset_i( height, var-> h);
404 pset_i( type, (var-> type == dbtBitmap) ? imBW : imRGB);
405 // create object
407 h = Object_create( className, profile);
408 // free profile, do not need it anymore
410 sv_free(( SV *) profile);
411 i = ( PDrawable) h;
413 s = i-> self-> get_size( h);
414 i-> self-> begin_paint( h);
415 i-> self-> put_image_indirect( h, self, 0, 0, 0, 0, s.x, s.y, s.x, s.y, ropCopyPut);
416 i-> self-> end_paint( h);
417 // decrement reference count
419 --SvREFCNT( SvRV( i-> mate));
420 return h;
421 }
422 Note that all code that would use this xdup(), have to increase and
424 decrease object's reference count if some perl functions are to be
425 executed before returning object to perl, otherwise it might be
426 destroyed before its time.
427 Handle x = xdup( self, "Prima::Image");
429 ++SvREFCNT( SvRV( PAnyObject(x)-> mate)); // Code without these
430 CImage( x)-> type( x, imbpp1);
431 --SvREFCNT( SvRV( PAnyObject(x)-> mate)); // brackets is unsafe
432 return x;
433 Attaching objects
435 The newly created object returned from C would be destroyed due perl's
436 garbage cleaning mechanism right away, unless the object value would be
437 assigned to a scalar, for example.
438 Thus
440 $c = Prima::Object-> create();
442 and
444 Prima::Object-> create;
445 have different results. But for some classes, namely Widget ant its
447 descendants, and also for Timer, AbstractMenu, Printer and Clipboard
448 the code above would have same result - the objects would not be
449 killed. That is because these objects call Component_attach() during
450 init-stage, automatically increasing their reference count.
451 Component_attach() and its reverse Component_detach() account list of
452 objects, attributed to each other. Object can be attached to multiple
453 objects, but cannot be attached more that once to another object.
454 Notifications
456 All Prima::Component descendants are equipped with the mechanism that
457 allows multiple user callbacks routines to be called on different
458 events. This mechanism is used heavily in event-driven programming.
459 Component_notify() is used to call user notifications, and its format
460 string has same format as accepted by perl_call_indirect(). The only
461 difference that it always has to be prepended with '<s', - this way the
462 call success flag is set, and first parameter have to be the name of
463 the notification.
464 Component_notify( self, "<sH", "Paint", self);
466 Component_notify( self, "<sPii", "MouseDown", self, point, int, int);
467 Notifications mechanism accounts the reference list, similar to attach-
469 detach mechanism, because all notifications can be attributed to
470 different objects. The membership in this list does not affect the
471 reference counting.
472 Multiple property setting
474 Prima::Object method set() is designed to assign several properties at
475 one time. Sometimes it is more convenient to write
476 $c-> set( index => 10, name => "Sample" );
478 than to invoke several methods one by one. set() performs this calling
480 itself, but for performance reasons it is possible to overload this
481 method and code special conditions for multiple assignment. As an
482 example, Prima::Image type conversion code is exemplified:
483 void
485 Image_set( Handle self, HV * profile)
486 {
487 ...
488 if ( pexist( type))
489 {
490 int newType = pget_i( type);
491 if ( !itype_supported( newType))
492 warn("Invalid image type requested (%08x) in Image::set_type",
493 newType);
494 else
495 if ( !opt_InPaint)
496 my-> reset( self, newType, pexist( palette) ?
497 pget_sv( palette) : my->get_palette( self));
498 pdelete( palette);
499 pdelete( type);
500 }
501 ...
502 inherited set ( self, profile);
503 }
504 If type conversion is performed along with palette change, some
506 efficiency is gained by supplying both 'type' and 'palette' parameters
507 at a time. Moreover, because ordering of the fields is not determined
508 by default ( although that be done by supplying '__ORDER__' hash key to
509 set() }, it can easily be discovered that
510 $image-> type( $a);
512 $image-> palette( $b);
513 and
515 $image-> palette( $b);
517 $image-> type( $a);
518 produce different results. Therefore it might be only solution to code
520 Class_set() explicitly.
521 If it is desired to specify exact order how atomic properties have to
523 be called, __ORDER__ anonymous array have to be added to set()
524 parameters.
525 $image-> set(
527 owner => $xxx,
528 type => 24,
529 __ORDER__ => [qw( type owner)],
530 );
531
533 Variables
534 primaObjects, PHash
535 Hash with all prima objects, where keys are their data instances
536 application, Handle
538 Pointer to an application. There can be only one Application
539 instance at a time, or none at all.
540 Macros and functions
542 dG_EVAL_ARGS
543 Defines variable for $@ value storage
544 OPEN_G_EVAL, CLOSE_G_EVAL
546 Brackets for exception catching
547 build_static_vmt
549 Bool(void * vmt)
550 Caches pre-built VMT for further use
552 build_dynamic_vmt
554 Bool( void * vmt, char * ancestorName, int ancestorVmtSize)
555 Creates a subclass from vmt and caches result under ancestorName
557 key
558 gimme_the_vmt
560 PVMT( const char *className);
561 Returns VMT pointer associated with class by name.
563 gimme_the_mate
565 Handle( SV * perlObject)
566 Returns a C pointer to an object, if perlObject is a reference to a
568 Prima object. returns nilHandle if object's stage is csDead
569 gimme_the_real_mate
571 Handle( SV * perlObject)
572 Returns a C pointer to an object, if perlObject is a reference to a
574 Prima object. Same as "gimme_the_mate", but does not check for the
575 object stage.
576 alloc1
578 alloc1(type)
579 To be used instead (type*)(malloc(sizeof(type))
581 allocn
583 allocn(type,n)
584 To be used instead (type*)(malloc((n)*sizeof(type))
586 alloc1z
588 Same as "alloc1" but fills the allocated memory with zeros
589 allocnz
591 Same as "allocn" but fills the allocated memory with zeros
592 prima_mallocz
594 Same as malloc() but fills the allocated memory with zeros
595 prima_hash_create
597 PHash(void)
598 Creates an empty hash
600 prima_hash_destroy
602 void(PHash self, Bool killAll);
603 Destroys a hash. If killAll is true, assumes that every value in
605 the hash is a dynamic memory pointer and calls free() on each.
606 prima_hash_fetch
608 void*( PHash self, const void *key, int keyLen);
609 Returns pointer to a value, if found, nil otherwise
611 prima_hash_delete
613 void*( PHash self, const void *key, int keyLen, Bool kill);
614 Deletes hash key and returns associated value. if kill is true,
616 calls free() on the value and returns nil.
617 prima_hash_store
619 void( PHash self, const void *key, int keyLen, void *val);
620 Stores new value into hash. If the key is already present, old
622 value is overwritten.
623 prima_hash_count
625 int(PHash self)
626 Returns number of keys in the hash
628 prima_hash_first_that
630 void * ( PHash self, void *action, void *params, int *pKeyLen, void **pKey);
631 Enumerates all hash entries, calling action procedure on each. If
633 the action procedure returns true, enumeration stops and the last
634 processed value is returned. Otherwise nil is returned. action have
635 to be function declared as
636 Bool action_callback( void * value, int keyLen, void * key, void * params);
638 params is a pointer to an arbitrary user data
640 kind_of
642 Bool( Handle object, void *cls);
643 Returns true, if the object is an exemplar of class cls or its
645 descendant
646 PERL_CALL_METHOD, PERL_CALL_PV
648 To be used instead of perl_call_method and perl_call_pv, described
649 in perlguts manpage. These functions aliased to a code with the
650 workaround of perl bug which emerges when G_EVAL flag is combined
651 with G_SCALAR.
652 eval
654 SV *( char *string)
655 Simplified perl_eval_pv() call.
657 sv_query_method
659 CV * ( SV * object, char *methodName, Bool cacheIt);
660 Returns perl pointer to a method searched by a scalar and a name If
662 cacheIt true, caches the hierarchy traverse result for a speedup.
663 query_method
665 CV * ( Handle object, char *methodName, Bool cacheIt);
666 Returns perl pointer to a method searched by an object and a name
668 If cacheIt true, caches the hierarchy traverse result for a
669 speedup.
670 call_perl_indirect
672 SV * ( Handle self, char *subName, const char *format, Bool cdecl,
673 Bool coderef, va_list params);
674 Core function for calling Prima methods. Is used by the following
676 three functions, but is never called directly. Format is described
677 in "Calling perl code" section.
678 call_perl
680 SV * ( Handle self, char *subName, const char *format, ...);
681 Calls method of an object pointer by a Handle
683 sv_call_perl
685 SV * ( SV * mate, char *subName, const char *format, ...);
686 Calls method of an object pointed by a SV*
688 cv_call_perl
690 SV * ( SV * mate, Sv * coderef, const char *format, ...);
691 Calls arbitrary perl code with mate as first parameter. Used in
693 notifications mechanism.
694 Object_create
696 Handle( char * className, HV * profile);
697 Creates an exemplar of className class with parameters in profile.
699 Never returns nilHandle, throws an exception instead.
700 create_object
702 void*( const char *objClass, const char *format, ...);
703 Convenience wrapper to Object_create. Uses format specification
705 that is described in "Calling perl code".
706 create_instance
708 Handle( const char * className)
709 Convenience call to "Object_create" with parameters in hash
711 'profile'.
712 Object_destroy
714 void( Handle self);
715 Destroys object. One of few Prima function that can be called in
717 re-entrant fashion.
718 Object_alive
720 void( Handle self);
721 Returns non-zero is object is alive, 0 otherwise. In particular,
723 current implementation returns 1 if object's stage is csNormal and
724 2 if it is csConstructing. Has virtually no use in C, only used in
725 perl code.
726 protect_object
728 void( Handle obj);
729 restricts object pointer from deletion after Object_destroy(). Can
731 be called several times on an object. Increments Object.
732 protectCount.
733 unprotect_object
735 void( Handle obj);
736 Frees object pointer after Object. protectCount hits zero. Can be
738 called several times on an object.
739 parse_hv
741 HV *( I32 ax, SV **sp, I32 items, SV **mark, int expected, const char *methodName);
742 Transfers arguments in perl stack to a newly created HV and returns
744 it.
745 push_hv
747 void ( I32 ax, SV **sp, I32 items, SV **mark, int callerReturns, HV *hv);
748 Puts all hv contents back to perl stack.
750 push_hv_for_REDEFINED
752 SV **( SV **sp, HV *hv);
753 Puts hv content as arguments to perl code to be called
755 pop_hv_for_REDEFINED
757 int ( SV **sp, int count, HV *hv, int shouldBe);
758 Reads result of executed perl code and stores them into hv.
760 pexist
762 Bool(char*key)
763 Return true if a key is present into hash 'profile'
765 pdelete
767 void(char*key)
768 Deletes a key in hash 'profile'
770 pget_sv, pget_i, pget_f, pget_c, pget_H, pget_B
772 TYPE(char*key)
773 Returns value of ( SV*, int, float, char*, Handle or Bool) that is
775 associated to a key in hash 'profile'. Calls croak() if the key is
776 not present.
777 pset_sv, pset_i, pset_f, pset_c, pset_H
779 void( char*key, TYPE value)
780 Assigns a value to a key in hash 'profile' and increments reference
782 count to a newly created scalar.
783 pset_b
785 void( char*key, void* data, int length)
786 Assigns binary data to a key in hash 'profile' and increments
788 reference count to a newly created scalar.
789 pset_sv_noinc
791 void(char* key, SV * sv)
792 Assigns scalar value to a key in hash 'profile' without reference
794 count increment.
795 duplicate_string
797 char*( const char *)
798 Returns copy of a string
800 list_create
802 void ( PList self, int size, int delta);
803 Creates a list instance with a static List structure.
805 plist_create
807 PList( int size, int delta);
808 Created list instance and returns newly allocated List structure.
810 list_destroy
812 void( PList self);
813 Destroys list data.
815 plist_destroy
817 void ( PList self);
818 Destroys list data and frees list instance.
820 list_add
822 int( PList self, Handle item);
823 Adds new item into a list, returns its index or -1 on error.
825 list_insert_at
827 int ( PList self, Handle item, int pos);
828 Inserts new item into a list at a given position, returns its
830 position or -1 on error.
831 list_at
833 Handle ( PList self, int index);
834 Returns items that is located at given index or nilHandle if the
836 index is out of range.
837 list_delete
839 void( PList self, Handle item);
840 Removes the item from list.
842 list_delete_at
844 void( PList self, int index);
845 Removes the item located at given index from a list.
847 list_delete_all
849 void ( PList self, Bool kill);
850 Removes all items from the list. If kill is true, calls free() on
852 every item before.
853 list_first_that
855 int( PList self, void * action, void * params);
856 Enumerates all list entries, calling action procedure on each. If
858 action returns true, enumeration stops and the index is returned.
859 Otherwise -1 is returned. action have to be a function declared as
860 Bool action_callback( Handle item, void * params);
862 params is a pointer to an arbitrary user data
864 list_index_of
866 int( PList self, Handle item);
867 Returns index of an item, or -1 if the item is not in the list.
869
871 Dmitry Karasik, <dmitry@karasik.eu.org>.
872
874 Prima
875perl v5.28.0 2017-02-28 pod::Prima::internals(3)