From a4f1a0295dfc0733a51ca0623d486d082d04773a Mon Sep 17 00:00:00 2001 From: Nick Ing-Simmons Date: Fri, 8 Feb 2002 09:19:29 +0000 Subject: Extract something from yesterdays effort - convert my mail on pad data structures (incoporating Sarathy's corrections/clarifications) into POD in cv.h which gets autodoc.pl'ed into pod/perlintern.pod. p4raw-id: //depot/perlio@14595 --- pod/perlapi.pod | 222 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 122 insertions(+), 100 deletions(-) (limited to 'pod/perlapi.pod') diff --git a/pod/perlapi.pod b/pod/perlapi.pod index d55b88a13a..dc52664ef7 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -1266,6 +1266,16 @@ argument more than once. =for hackers Found in file sv.h +=item SvLOCK + +Arranges for a mutual exclusion lock to be obtained on sv if a suitable module +has been loaded. + + void SvLOCK(SV* sv) + +=for hackers +Found in file sv.h + =item SvSETMAGIC Invokes C on an SV if it has 'set' magic. This macro evaluates its @@ -1285,6 +1295,15 @@ Like C, but does any set magic required afterwards. =for hackers Found in file sv.h +=item SvSetMagicSV_nosteal + +Like C, but does any set magic required afterwards. + + void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.h + =item SvSetSV Calls C if dsv is not the same as ssv. May evaluate arguments @@ -1305,6 +1324,16 @@ ssv. May evaluate arguments more than once. =for hackers Found in file sv.h +=item SvSHARE + +Arranges for sv to be shared between threads if a suitable module +has been loaded. + + void SvSHARE(SV* sv) + +=for hackers +Found in file sv.h + =back @@ -1417,13 +1446,24 @@ Found in file util.c =item savepvn Copy a string to a safe spot. The C indicates number of bytes to -copy. This does not use an SV. +copy. If pointer is NULL allocate space for a string of size specified. +This does not use an SV. char* savepvn(const char* sv, I32 len) =for hackers Found in file util.c +=item savesharedpv + +Copy a string to a safe spot in memory shared between threads. +This does not use an SV. + + char* savesharedpv(const char* sv) + +=for hackers +Found in file util.c + =item StructCopy This is an architecture-independent macro to copy one structure to another. @@ -1748,77 +1788,6 @@ Used by C to hook up XSUBs as Perl subs. Found in file op.c -=back - -=head1 Shared SV Functions - -=over 8 - -=item sharedsv_find - -Tries to find if a given SV has a shared backend, either by -looking at magic, or by checking if it is tied again threads::shared. - - shared_sv* sharedsv_find(SV* sv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_init - -Saves a space for keeping SVs wider than an interpreter, -currently only stores a pointer to the first interpreter. - - void sharedsv_init() - -=for hackers -Found in file sharedsv.c - -=item sharedsv_lock - -Recursive locks on a sharedsv. -Locks are dynamically scoped at the level of the first lock. - void sharedsv_lock(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_new - -Allocates a new shared sv struct, you must yourself create the SV/AV/HV. - shared_sv* sharedsv_new() - -=for hackers -Found in file sharedsv.c - -=item sharedsv_thrcnt_dec - -Decrements the threadcount of a shared sv. When a threads frontend is freed -this function should be called. - - void sharedsv_thrcnt_dec(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_thrcnt_inc - -Increments the threadcount of a sharedsv. - void sharedsv_thrcnt_inc(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_unlock - -Recursively unlocks a shared sv. - - void sharedsv_unlock(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - - =back =head1 Stack Manipulation Macros @@ -2899,21 +2868,21 @@ Like C, but converts sv to utf8 first if necessary. =for hackers Found in file sv.h -=item SvPVX +=item SvPVx -Returns a pointer to the physical string in the SV. The SV must contain a -string. +A version of C which guarantees to evaluate sv only once. - char* SvPVX(SV* sv) + char* SvPVx(SV* sv, STRLEN len) =for hackers Found in file sv.h -=item SvPVx +=item SvPVX -A version of C which guarantees to evaluate sv only once. +Returns a pointer to the physical string in the SV. The SV must contain a +string. - char* SvPVx(SV* sv, STRLEN len) + char* SvPVX(SV* sv) =for hackers Found in file sv.h @@ -3011,16 +2980,6 @@ Dereferences an RV to return the SV. =for hackers Found in file sv.h -=item SvSetMagicSV_nosteal - -Like C, but does any set magic required afterwards. - - - void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - =item SvSTASH Returns the stash of the SV. @@ -3091,6 +3050,17 @@ Returns the type of the SV. See C. =for hackers Found in file sv.h +=item SvUNLOCK + +Releases a mutual exclusion lock on sv if a suitable module +has been loaded. + + + void SvUNLOCK(SV* sv) + +=for hackers +Found in file sv.h + =item SvUOK Returns a boolean indicating whether the SV contains an unsigned integer. @@ -3148,22 +3118,22 @@ for a version which guarantees to evaluate sv only once. =for hackers Found in file sv.h -=item SvUVx +=item SvUVX -Coerces the given SV to an unsigned integer and returns it. Guarantees to -evaluate sv only once. Use the more efficient C otherwise. +Returns the raw value in the SV's UV slot, without checks or conversions. +Only use when you are sure SvIOK is true. See also C. - UV SvUVx(SV* sv) + UV SvUVX(SV* sv) =for hackers Found in file sv.h -=item SvUVX +=item SvUVx -Returns the raw value in the SV's UV slot, without checks or conversions. -Only use when you are sure SvIOK is true. See also C. +Coerces the given SV to an unsigned integer and returns it. Guarantees to +evaluate sv only once. Use the more efficient C otherwise. - UV SvUVX(SV* sv) + UV SvUVx(SV* sv) =for hackers Found in file sv.h @@ -3674,13 +3644,32 @@ Found in file sv.c Adds magic to an SV. First upgrades C to type C if necessary, then adds a new magic item of type C to the head of the magic list. -C is assumed to contain an C if C<(name && namelen == HEf_SVKEY)> - void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) =for hackers Found in file sv.c +=item sv_magicext + +Adds magic to an SV, upgrading it if necessary. Applies the +supplied vtable and returns pointer to the magic added. + +Note that sv_magicext will allow things that sv_magic will not. +In particular you can add magic to SvREADONLY SVs and and more than +one instance of the same 'how' + +I C is greater then zero then a savepvn() I of C is stored, +if C is zero then C is stored as-is and - as another special +case - if C<(name && namelen == HEf_SVKEY)> then C is assumed to contain +an C and has its REFCNT incremented + +(This is now used as a subroutine by sv_magic.) + + MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen ) + +=for hackers +Found in file sv.c + =item sv_mortalcopy Creates a new SV which is a copy of the original SV (using C). @@ -3715,6 +3704,39 @@ instead. =for hackers Found in file sv.c +=item sv_nolocking + +Dummy routine which "locks" an SV when there is no locking module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nolocking(SV *) + +=for hackers +Found in file util.c + +=item sv_nosharing + +Dummy routine which "shares" an SV when there is no sharing module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nosharing(SV *) + +=for hackers +Found in file util.c + +=item sv_nounlocking + +Dummy routine which "unlocks" an SV when there is no locking module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nounlocking(SV *) + +=for hackers +Found in file util.c + =item sv_nv A private implementation of the C macro for compilers which can't @@ -4477,7 +4499,7 @@ length len, the displayable version being at most pvlim bytes long (if longer, the rest is truncated and "..." will be appended). The flags argument can have UNI_DISPLAY_ISPRINT set to display -isprint()able characters as themselves, UNI_DISPLAY_BACKSLASH +isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH to display the \\[nrfta\\] as the backslashed versions (like '\n') (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\). UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both -- cgit v1.2.1