X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/6a5b4183fb7901110d40b26a7e60b0950cc9465d..02b54f9d07226e99a30271314e02617d5629b511:/perlvars.h diff --git a/perlvars.h b/perlvars.h index 96dfe04..02085fe 100644 --- a/perlvars.h +++ b/perlvars.h @@ -10,9 +10,14 @@ /* =head1 Global Variables - These variables are global to an entire process. They are shared between -all interpreters and all threads in a process. +all interpreters and all threads in a process. Any variables not documented +here may be changed or removed without notice, so don't use them! +If you feel you really do need to use an unlisted variable, first send email to +L. It may be that +someone there will point out a way to accomplish what you need without using an +internal variable. But if not, you should get a go-ahead to document and then +use the variable. =cut */ @@ -32,10 +37,10 @@ all interpreters and all threads in a process. #if defined(USE_ITHREADS) PERLVAR(G, op_mutex, perl_mutex) /* Mutex for op refcounting */ #endif -PERLVAR(G, curinterp, PerlInterpreter *) - /* currently running interpreter - * (initial parent interpreter under - * useithreads) */ +PERLVARI(G, curinterp, PerlInterpreter *, NULL) + /* currently running interpreter + * (initial parent interpreter under + * useithreads) */ #if defined(USE_ITHREADS) PERLVAR(G, thr_key, perl_key) /* key to retrieve per-thread struct */ #endif @@ -43,16 +48,12 @@ PERLVAR(G, thr_key, perl_key) /* key to retrieve per-thread struct */ /* XXX does anyone even use this? */ PERLVARI(G, do_undump, bool, FALSE) /* -u or dump seen? */ -#ifndef PERL_USE_SAFE_PUTENV -PERLVARI(G, use_safe_putenv, bool, TRUE) -#endif - #if defined(FAKE_PERSISTENT_SIGNAL_HANDLERS)||defined(FAKE_DEFAULT_SIGNAL_HANDLERS) PERLVARI(G, sig_handlers_initted, int, 0) #endif #ifdef FAKE_PERSISTENT_SIGNAL_HANDLERS PERLVARA(G, sig_ignoring, SIG_SIZE, int) - /* which signals we are ignoring */ + /* which signals we are ignoring */ #endif #ifdef FAKE_DEFAULT_SIGNAL_HANDLERS PERLVARA(G, sig_defaulting, SIG_SIZE, int) @@ -68,8 +69,13 @@ PERLVARI(G, sig_trapped, int, 0) /* If Perl has to ignore SIGPFE, this is its saved state. * See perl.h macros PERL_FPU_INIT and PERL_FPU_{PRE,POST}_EXEC. */ PERLVAR(G, sigfpe_saved, Sighandler_t) -PERLVARI(G, csighandlerp, Sighandler_t, Perl_csighandler) - /* Pointer to C-level sighandler */ + +/* these ptrs to functions are to avoid linkage problems; see + * perl-5.8.0-2193-g5c1546dc48 + */ +PERLVARI(G, csighandlerp, Sighandler_t, Perl_csighandler) +PERLVARI(G, csighandler1p, Sighandler1_t, Perl_csighandler1) +PERLVARI(G, csighandler3p, Sighandler3_t, Perl_csighandler3) #endif /* This is constant on most architectures, a global on OS/2 */ @@ -94,14 +100,18 @@ PERLVARI(G, mmap_page_size, IV, 0) #if defined(USE_ITHREADS) PERLVAR(G, hints_mutex, perl_mutex) /* Mutex for refcounted he refcounting */ +PERLVAR(G, env_mutex, perl_RnW1_mutex_t) /* Mutex for accessing ENV */ +PERLVAR(G, locale_mutex, perl_mutex) /* Mutex related to locale handling */ #endif -#ifdef DEBUGGING -PERLVAR(G, watch_pvx, char *) +#ifdef USE_POSIX_2008_LOCALE +PERLVARI(G, C_locale_obj, locale_t, NULL) #endif +PERLVARI(G, watch_pvx, char *, NULL) + /* -=for apidoc AmU|Perl_check_t *|PL_check +=for apidoc AmnU|Perl_check_t *|PL_check Array, indexed by opcode, of functions that will be called for the "check" phase of optree building during compilation of Perl code. For most (but @@ -129,31 +139,37 @@ with the core's base checker at the end. For thread safety, modules should not write directly to this array. Instead, use the function L. +=for apidoc Amn|enum perl_phase|PL_phase + +A value that indicates the current Perl interpreter's phase. Possible values +include C, C, C, +C, C, C, and +C. + +For example, the following determines whether the interpreter is in +global destruction: + + if (PL_phase == PERL_PHASE_DESTRUCT) { + // we are in global destruction + } + +C was introduced in Perl 5.14; in prior perls you can use +C (boolean) to determine whether the interpreter is in global +destruction. (Use of C is discouraged since 5.14.) + =cut */ #if defined(USE_ITHREADS) PERLVAR(G, check_mutex, perl_mutex) /* Mutex for PL_check */ #endif -#ifdef PERL_GLOBAL_STRUCT -PERLVAR(G, ppaddr, Perl_ppaddr_t *) /* or opcode.h */ -PERLVAR(G, check, Perl_check_t *) /* or opcode.h */ -PERLVARA(G, fold_locale, 256, unsigned char) /* or perl.h */ -#endif - -#ifdef PERL_NEED_APPCTX -PERLVAR(G, appctx, void*) /* the application context */ -#endif - -#if defined(HAS_TIMES) && defined(PERL_NEED_TIMESBASE) -PERLVAR(G, timesbase, struct tms) -#endif /* allocate a unique index to every module that calls MY_CXT_INIT */ -#ifdef PERL_IMPLICIT_CONTEXT +#ifdef MULTIPLICITY # ifdef USE_ITHREADS PERLVAR(G, my_ctx_mutex, perl_mutex) +PERLVARI(G, veto_switch_non_tTHX_context, int, FALSE) # endif PERLVARI(G, my_cxt_index, int, 0) #endif @@ -163,14 +179,14 @@ PERLVARI(G, my_cxt_index, int, 0) PERLVARI(G, veto_cleanup, int, FALSE) /* exit without cleanup */ /* -=for apidoc AmUx|Perl_keyword_plugin_t|PL_keyword_plugin +=for apidoc AmnUx|Perl_keyword_plugin_t|PL_keyword_plugin Function pointer, pointing at a function used to handle extended keywords. The function should be declared as - int keyword_plugin_function(pTHX_ - char *keyword_ptr, STRLEN keyword_len, - OP **op_ptr) + int keyword_plugin_function(pTHX_ + char *keyword_ptr, STRLEN keyword_len, + OP **op_ptr) The function is called from the tokeniser, whenever a possible keyword is seen. C points at the word in the parser's input @@ -212,12 +228,115 @@ at a chain of handler functions, all of which have an opportunity to handle keywords, and only the last function in the chain (built into the Perl core) will normally return C. +For thread safety, modules should not set this variable directly. +Instead, use the function L. + =cut */ +#if defined(USE_ITHREADS) +PERLVAR(G, keyword_plugin_mutex, perl_mutex) /* Mutex for PL_keyword_plugin and PL_infix_plugin */ +#endif PERLVARI(G, keyword_plugin, Perl_keyword_plugin_t, Perl_keyword_plugin_standard) -PERLVAR(G, op_sequence, HV *) /* dump.c */ +/* +=for apidoc AmnUx|Perl_infix_plugin_t|PL_infix_plugin + +B This API exists entirely for the purpose of making the CPAN module +C work. It is not expected that additional modules will make +use of it; rather, that they should use C to provide parsing +of new infix operators. + +Function pointer, pointing at a function used to handle extended infix +operators. The function should be declared as + + int infix_plugin_function(pTHX_ + char *opname, STRLEN oplen, + struct Perl_custom_infix **infix_ptr) + +The function is called from the tokenizer whenever a possible infix operator +is seen. C points to the operator name in the parser's input buffer, +and C gives the I number of bytes of it that should be +consumed; it is not null-terminated. The function is expected to examine the +operator name and possibly other state such as L<%^H|perlvar/%^H>, to +determine whether it wants to handle the operator name. + +As compared to the single stage of C, parsing of additional +infix operators occurs in three separate stages. This is because of the more +complex interactions it has with the parser, to ensure that operator +precedence rules work correctly. These stages are co-ordinated by the use of +an additional information structure. + +If the function wants to handle the infix operator, it must set the variable +pointed to by C to the address of a structure that provides this +additional information about the subsequent parsing stages. If it does not, +it should make a call to the next function in the chain. + +This structure has the following definition: + + struct Perl_custom_infix { + enum Perl_custom_infix_precedence prec; + void (*parse)(pTHX_ SV **opdata, + struct Perl_custom_infix *); + OP *(*build_op)(pTHX_ SV **opdata, OP *lhs, OP *rhs, + struct Perl_custom_infix *); + }; + +The function must then return an integer giving the number of bytes consumed +by the name of this operator. In the case of an operator whose name is +composed of identifier characters, this must be equal to C. In the case +of an operator named by non-identifier characters, this is permitted to be +shorter than C, and any additional characters after it will not be +claimed by the infix operator but instead will be consumed by the tokenizer +and parser as normal. + +If the optional C function is provided, it is called immediately by the +parser to let the operator's definition consume any additional syntax from the +source code. This should I be used for normal operand parsing, but it may +be useful when implementing things like parametric operators or meta-operators +that consume more syntax themselves. This function may use the variable +pointed to by C to provide an SV containing additional data to be +passed into the C function later on. + +The information structure gives the operator precedence level in the C +field. This is used to tell the parser how much of the surrounding syntax +before and after should be considered as operands to the operator. + +The tokenizer and parser will then continue to operate as normal until enough +additional input has been parsed to form both the left- and right-hand side +operands to the operator, according to the precedence level. At this point the +C function is called, being passed the left- and right-hand operands +as optree fragments. It is expected to combine them into the resulting optree +fragment, which it should return. + +After the C function has returned, if the variable pointed to by +C was set to a non-C value, it will then be destroyed by calling +C. + +For thread safety, modules should not set this variable directly. +Instead, use the function L. + +However, that all said, the introductory note above still applies. This +variable is provided in core perl only for the benefit of the +C module. That module acts as a central registry for infix +operators, automatically handling things like deparse support and +discovery/reflection, and these abilities only work because it knows all the +registered operators. Other modules should not use this interpreter variable +directly to implement them because then those central features would no longer +work properly. + +Furthermore, it is likely that this (experimental) API will be replaced in a +future Perl version by a more complete API that fully implements the central +registry and other semantics currently provided by C, once +the module has had sufficient experimental testing time. This current +mechanism exists only as an interim measure to get to that stage. + +=cut +*/ + +PERLVARI(G, infix_plugin, Perl_infix_plugin_t, Perl_infix_plugin_standard) + +PERLVARI(G, op_sequence, HV *, NULL) /* dump.c */ PERLVARI(G, op_seq, UV, 0) /* dump.c */ #ifdef USE_ITHREADS @@ -225,7 +344,10 @@ PERLVAR(G, dollarzero_mutex, perl_mutex) /* Modifying $0 */ #endif /* Restricted hashes placeholder value. - * The contents are never used, only the address. */ + In theory, the contents are never used, only the address. + In practice, &PL_sv_placeholder is returned by some APIs, and the calling + code is checking SvOK(). */ + PERLVAR(G, sv_placeholder, SV) #if defined(MYMALLOC) && defined(USE_ITHREADS) @@ -233,4 +355,48 @@ PERLVAR(G, malloc_mutex, perl_mutex) /* Mutex for malloc */ #endif PERLVARI(G, hash_seed_set, bool, FALSE) /* perl.c */ -PERLVARA(G, hash_seed, PERL_HASH_SEED_BYTES, unsigned char) /* perl.c and hv.h */ +PERLVARA(G, hash_seed_w, PERL_HASH_SEED_WORDS, PVT__PERL_HASH_WORD_TYPE) /* perl.c and hv.h */ +#if defined(PERL_HASH_STATE_BYTES) +PERLVARA(G, hash_state_w, PERL_HASH_STATE_WORDS, PVT__PERL_HASH_WORD_TYPE) /* perl.c and hv.h */ +#endif +#if defined(PERL_USE_SINGLE_CHAR_HASH_CACHE) +#define PERL_SINGLE_CHAR_HASH_CACHE_ELEMS ((1+256) * sizeof(U32)) +PERLVARA(G, hash_chars, PERL_SINGLE_CHAR_HASH_CACHE_ELEMS, unsigned char) /* perl.c and hv.h */ +#endif + +/* The path separator can vary depending on whether we're running under DCL or + * a Unix shell. + */ +#ifdef __VMS +PERLVAR(G, perllib_sep, char) +#endif + +/* Definitions of user-defined \p{} properties, as the subs that define them + * are only called once */ +PERLVARI(G, user_def_props, HV *, NULL) + +#if defined(USE_ITHREADS) +PERLVAR(G, user_def_props_aTHX, PerlInterpreter *) /* aTHX that user_def_props + was defined in */ +PERLVAR(G, user_prop_mutex, perl_mutex) /* Mutex for manipulating + PL_user_defined_properties */ +#endif + +/* these record the best way to perform certain IO operations while + * atomically setting FD_CLOEXEC. On the first call, a probe is done + * and the result recorded for use by subsequent calls. + * In theory these variables aren't thread-safe, but the worst that can + * happen is that two treads will both do an initial probe + */ +PERLVARI(G, strategy_dup, int, 0) /* doio.c */ +PERLVARI(G, strategy_dup2, int, 0) /* doio.c */ +PERLVARI(G, strategy_open, int, 0) /* doio.c */ +PERLVARI(G, strategy_open3, int, 0) /* doio.c */ +PERLVARI(G, strategy_mkstemp, int, 0) /* doio.c */ +PERLVARI(G, strategy_socket, int, 0) /* doio.c */ +PERLVARI(G, strategy_accept, int, 0) /* doio.c */ +PERLVARI(G, strategy_pipe, int, 0) /* doio.c */ +PERLVARI(G, strategy_socketpair, int, 0) /* doio.c */ + +PERLVARI(G, my_environ, char **, NULL) +PERLVARI(G, origenviron, char **, NULL)