perlvars.h revision 1.2
1/* perlvars.h 2 * 3 * Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 4 * by Larry Wall and others 5 * 6 * You may distribute under the terms of either the GNU General Public 7 * License or the Artistic License, as specified in the README file. 8 * 9 */ 10 11/* 12=head1 Global Variables 13These variables are global to an entire process. They are shared between 14all interpreters and all threads in a process. Any variables not documented 15here may be changed or removed without notice, so don't use them! 16If you feel you really do need to use an unlisted variable, first send email to 17L<perl5-porters@perl.org|mailto:perl5-porters@perl.org>. It may be that 18someone there will point out a way to accomplish what you need without using an 19internal variable. But if not, you should get a go-ahead to document and then 20use the variable. 21 22=cut 23*/ 24 25/* Don't forget to re-run regen/embed.pl to propagate changes! */ 26 27/* This file describes the "global" variables used by perl 28 * This used to be in perl.h directly but we want to abstract out into 29 * distinct files which are per-thread, per-interpreter or really global, 30 * and how they're initialized. 31 * 32 * The 'G' prefix is only needed for vars that need appropriate #defines 33 * generated in embed*.h. Such symbols are also used to generate 34 * the appropriate export list for win32. */ 35 36/* global state */ 37#if defined(USE_ITHREADS) 38PERLVAR(G, op_mutex, perl_mutex) /* Mutex for op refcounting */ 39#endif 40PERLVARI(G, curinterp, PerlInterpreter *, NULL) 41 /* currently running interpreter 42 * (initial parent interpreter under 43 * useithreads) */ 44#if defined(USE_ITHREADS) 45PERLVAR(G, thr_key, perl_key) /* key to retrieve per-thread struct */ 46#endif 47 48/* XXX does anyone even use this? */ 49PERLVARI(G, do_undump, bool, FALSE) /* -u or dump seen? */ 50 51#ifndef PERL_USE_SAFE_PUTENV 52PERLVARI(G, use_safe_putenv, bool, TRUE) 53#endif 54 55#if defined(FAKE_PERSISTENT_SIGNAL_HANDLERS)||defined(FAKE_DEFAULT_SIGNAL_HANDLERS) 56PERLVARI(G, sig_handlers_initted, int, 0) 57#endif 58#ifdef FAKE_PERSISTENT_SIGNAL_HANDLERS 59PERLVARA(G, sig_ignoring, SIG_SIZE, int) 60 /* which signals we are ignoring */ 61#endif 62#ifdef FAKE_DEFAULT_SIGNAL_HANDLERS 63PERLVARA(G, sig_defaulting, SIG_SIZE, int) 64#endif 65 66/* XXX signals are process-wide anyway, so we 67 * ignore the implications of this for threading */ 68#ifndef HAS_SIGACTION 69PERLVARI(G, sig_trapped, int, 0) 70#endif 71 72#ifndef PERL_MICRO 73/* If Perl has to ignore SIGPFE, this is its saved state. 74 * See perl.h macros PERL_FPU_INIT and PERL_FPU_{PRE,POST}_EXEC. */ 75PERLVAR(G, sigfpe_saved, Sighandler_t) 76PERLVARI(G, csighandlerp, Sighandler_t, Perl_csighandler) 77 /* Pointer to C-level sighandler */ 78#endif 79 80/* This is constant on most architectures, a global on OS/2 */ 81#ifdef OS2 82PERLVARI(G, sh_path, char *, SH_PATH) /* full path of shell */ 83#endif 84 85#ifdef USE_PERLIO 86 87# if defined(USE_ITHREADS) 88PERLVAR(G, perlio_mutex, perl_mutex) /* Mutex for perlio fd refcounts */ 89# endif 90 91PERLVARI(G, perlio_fd_refcnt, int *, 0) /* Pointer to array of fd refcounts. */ 92PERLVARI(G, perlio_fd_refcnt_size, int, 0) /* Size of the array */ 93PERLVARI(G, perlio_debug_fd, int, 0) /* the fd to write perlio debug into, 0 means not set yet */ 94#endif 95 96#ifdef HAS_MMAP 97PERLVARI(G, mmap_page_size, IV, 0) 98#endif 99 100#if defined(USE_ITHREADS) 101PERLVAR(G, hints_mutex, perl_mutex) /* Mutex for refcounted he refcounting */ 102PERLVAR(G, locale_mutex, perl_mutex) /* Mutex for setlocale() changing */ 103 104#endif 105 106#ifdef DEBUGGING 107PERLVARI(G, watch_pvx, char *, NULL) 108#endif 109 110/* 111=for apidoc AmU|Perl_check_t *|PL_check 112 113Array, indexed by opcode, of functions that will be called for the "check" 114phase of optree building during compilation of Perl code. For most (but 115not all) types of op, once the op has been initially built and populated 116with child ops it will be filtered through the check function referenced 117by the appropriate element of this array. The new op is passed in as the 118sole argument to the check function, and the check function returns the 119completed op. The check function may (as the name suggests) check the op 120for validity and signal errors. It may also initialise or modify parts of 121the ops, or perform more radical surgery such as adding or removing child 122ops, or even throw the op away and return a different op in its place. 123 124This array of function pointers is a convenient place to hook into the 125compilation process. An XS module can put its own custom check function 126in place of any of the standard ones, to influence the compilation of a 127particular type of op. However, a custom check function must never fully 128replace a standard check function (or even a custom check function from 129another module). A module modifying checking must instead B<wrap> the 130preexisting check function. A custom check function must be selective 131about when to apply its custom behaviour. In the usual case where 132it decides not to do anything special with an op, it must chain the 133preexisting op function. Check functions are thus linked in a chain, 134with the core's base checker at the end. 135 136For thread safety, modules should not write directly to this array. 137Instead, use the function L</wrap_op_checker>. 138 139=cut 140*/ 141 142#if defined(USE_ITHREADS) 143PERLVAR(G, check_mutex, perl_mutex) /* Mutex for PL_check */ 144#endif 145#ifdef PERL_GLOBAL_STRUCT 146PERLVAR(G, ppaddr, Perl_ppaddr_t *) /* or opcode.h */ 147PERLVAR(G, check, Perl_check_t *) /* or opcode.h */ 148PERLVARA(G, fold_locale, 256, unsigned char) /* or perl.h */ 149#endif 150 151#ifdef PERL_NEED_APPCTX 152PERLVAR(G, appctx, void*) /* the application context */ 153#endif 154 155#if defined(HAS_TIMES) && defined(PERL_NEED_TIMESBASE) 156PERLVAR(G, timesbase, struct tms) 157#endif 158 159/* allocate a unique index to every module that calls MY_CXT_INIT */ 160 161#ifdef PERL_IMPLICIT_CONTEXT 162# ifdef USE_ITHREADS 163PERLVAR(G, my_ctx_mutex, perl_mutex) 164# endif 165PERLVARI(G, my_cxt_index, int, 0) 166#endif 167 168/* this is currently set without MUTEX protection, so keep it a type which 169 * can be set atomically (ie not a bit field) */ 170PERLVARI(G, veto_cleanup, int, FALSE) /* exit without cleanup */ 171 172/* 173=for apidoc AmUx|Perl_keyword_plugin_t|PL_keyword_plugin 174 175Function pointer, pointing at a function used to handle extended keywords. 176The function should be declared as 177 178 int keyword_plugin_function(pTHX_ 179 char *keyword_ptr, STRLEN keyword_len, 180 OP **op_ptr) 181 182The function is called from the tokeniser, whenever a possible keyword 183is seen. C<keyword_ptr> points at the word in the parser's input 184buffer, and C<keyword_len> gives its length; it is not null-terminated. 185The function is expected to examine the word, and possibly other state 186such as L<%^H|perlvar/%^H>, to decide whether it wants to handle it 187as an extended keyword. If it does not, the function should return 188C<KEYWORD_PLUGIN_DECLINE>, and the normal parser process will continue. 189 190If the function wants to handle the keyword, it first must 191parse anything following the keyword that is part of the syntax 192introduced by the keyword. See L</Lexer interface> for details. 193 194When a keyword is being handled, the plugin function must build 195a tree of C<OP> structures, representing the code that was parsed. 196The root of the tree must be stored in C<*op_ptr>. The function then 197returns a constant indicating the syntactic role of the construct that 198it has parsed: C<KEYWORD_PLUGIN_STMT> if it is a complete statement, or 199C<KEYWORD_PLUGIN_EXPR> if it is an expression. Note that a statement 200construct cannot be used inside an expression (except via C<do BLOCK> 201and similar), and an expression is not a complete statement (it requires 202at least a terminating semicolon). 203 204When a keyword is handled, the plugin function may also have 205(compile-time) side effects. It may modify C<%^H>, define functions, and 206so on. Typically, if side effects are the main purpose of a handler, 207it does not wish to generate any ops to be included in the normal 208compilation. In this case it is still required to supply an op tree, 209but it suffices to generate a single null op. 210 211That's how the C<*PL_keyword_plugin> function needs to behave overall. 212Conventionally, however, one does not completely replace the existing 213handler function. Instead, take a copy of C<PL_keyword_plugin> before 214assigning your own function pointer to it. Your handler function should 215look for keywords that it is interested in and handle those. Where it 216is not interested, it should call the saved plugin function, passing on 217the arguments it received. Thus C<PL_keyword_plugin> actually points 218at a chain of handler functions, all of which have an opportunity to 219handle keywords, and only the last function in the chain (built into 220the Perl core) will normally return C<KEYWORD_PLUGIN_DECLINE>. 221 222=cut 223*/ 224 225PERLVARI(G, keyword_plugin, Perl_keyword_plugin_t, Perl_keyword_plugin_standard) 226 227PERLVARI(G, op_sequence, HV *, NULL) /* dump.c */ 228PERLVARI(G, op_seq, UV, 0) /* dump.c */ 229 230#ifdef USE_ITHREADS 231PERLVAR(G, dollarzero_mutex, perl_mutex) /* Modifying $0 */ 232#endif 233 234/* Restricted hashes placeholder value. 235 In theory, the contents are never used, only the address. 236 In practice, &PL_sv_placeholder is returned by some APIs, and the calling 237 code is checking SvOK(). */ 238 239PERLVAR(G, sv_placeholder, SV) 240 241#if defined(MYMALLOC) && defined(USE_ITHREADS) 242PERLVAR(G, malloc_mutex, perl_mutex) /* Mutex for malloc */ 243#endif 244 245PERLVARI(G, hash_seed_set, bool, FALSE) /* perl.c */ 246PERLVARA(G, hash_seed, PERL_HASH_SEED_BYTES, unsigned char) /* perl.c and hv.h */ 247