hphp/runtime/base/attr.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present Facebook, Inc. (http://www.facebook.com)  |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16
  17 #ifndef incl_HPHP_ATTR_H_
  18 #define incl_HPHP_ATTR_H_
  19
  20 namespace HPHP {
  21 ///////////////////////////////////////////////////////////////////////////////
  22
  23 /*
  24  * Special properties on PHP classes, functions, and properties.
  25  *
  26  * Attr unions are stored as integers in .hhbc repositories, so incompatible
  27  * changes here require a schema version bump.
  28  *
  29  * TODO(#4513748): We're almost out of space in Attr---in fact, we already have
  30  * too many Attrs to fit in Class, which packs them into only 28 bits.  There's
  31  * no reason to share Attrs among unrelated objects, so we should really have
  32  * three different Attr types.
  33  */
  34 enum Attr {
  35   AttrNone                 = 0,         // class | property | method  //
  36                                         //       |          |         //
  37   // Does this function return by reference?     |          |         //
  38   AttrReference            = (1 <<  0), //       |          |    X    //
  39                                         //       |          |         //
  40   // Class forbids dynamic properties?  //       |          |         //
  41   AttrForbidDynamicProps   = (1 <<  0), //   X   |          |         //
  42                                         //       |          |         //
  43   // Method visibility.  The relative ordering of these is important. //
  44   // N.B. the values are overlayed with some of the no-override bits for magic
  45   // class methods (next), since they don't apply to classes.
  46   AttrPublic               = (1 <<  1), //       |    X     |    X    //
  47   AttrProtected            = (1 <<  2), //       |    X     |    X    //
  48   AttrPrivate              = (1 <<  3), //       |    X     |    X    //
  49                                         //       |          |         //
  50   // No-override bits for magic class methods.  If set, the class does not
  51   // define that magic function, and neither does any derived class.  Note that
  52   // the bit for __unset is further down due to Attr-sharing across types.
  53   AttrNoOverrideMagicGet   = (1 <<  1), //   X   |          |         //
  54   AttrNoOverrideMagicSet   = (1 <<  2), //   X   |          |         //
  55   AttrNoOverrideMagicIsset = (1 <<  3), //   X   |          |         //
  56   // N.B.: AttrEnum and AttrStatic overlap! But they can't be set on the
  57   // same things.
  58   // Is this class an enum?
  59   AttrEnum                 = (1 <<  4), //    X  |          |         //
  60   // Was this declared static, abstract, or final?          |         //
  61   AttrStatic               = (1 <<  4), //       |    X     |    X    //
  62   AttrAbstract             = (1 <<  5), //    X  |          |    X    //
  63   AttrFinal                = (1 <<  6), //    X  |          |    X    //
  64                                         //       |          |         //
  65   // Is this class an interface?        //       |          |         //
  66   AttrInterface            = (1 <<  7), //    X  |          |         //
  67                                         //       |          |         //
  68   // Indicates that a function does not make any explicit calls to other PHP
  69   // functions.  It may still call other user-level functions via re-entry
  70   // (e.g., for destructors and autoload), and it may make calls to builtins
  71   // using FCallBuiltin.                //       |          |         //
  72   AttrPhpLeafFn            = (1 <<  7), //       |          |    X    //
  73                                         //       |          |         //
  74   // Is this class a trait?  On methods, or properties, this indicates that
  75   // the method was imported from a trait.
  76   AttrTrait                = (1 <<  8), //    X  |    X     |    X    //
  77                                         //       |          |         //
  78   // Indicates that this function should be ignored in backtraces.    //
  79   AttrNoInjection          = (1 <<  9), //       |          |    X    //
  80   // Indicates a class has no derived classes that have a magic __unset method.
  81   AttrNoOverrideMagicUnset = (1 <<  9), //   X   |          |         //
  82                                         //       |          |         //
  83   // Indicates that the function or class is uniquely named among functions or
  84   // classes across the codebase.  Note that function and class names are in
  85   // separate namespaces, so it is possible to have a Func and Class which
  86   // share a name but both of which are unique.  |          |         //
  87   AttrUnique               = (1 << 10), //    X  |          |    X    //
  88                                         //       |          |         //
  89   // Indicates that a function can be used with fb_rename_function---even if
  90   // JitEnableRenameFunction is false --- and can be used with fb_intercept.
  91   // (Note: we could split this into two bits, since you can technically
  92   // pessimize less for fb_intercept than you need to for fb_rename_function,
  93   //  but we haven't done so at this point.)     |          |         //
  94   AttrInterceptable        = (1 << 11), //       |          |    X    //
  95                                         //       |          |         //
  96   // Traits have been flattened on this class.
  97   AttrNoExpandTrait        = (1 << 12), //    X  |          |         //
  98                                         //       |          |         //
  99   // Set on functions where the $this class may not be a subclass of the
 100   // context (scope) class.
 101   AttrHasForeignThis       = (1 << 12), //       |          |    X    //
 102                                         //       |          |         //
 103   // Only valid in WholeProgram mode.  Indicates on a class that the class is
 104   // not extended, or on a method that no extending class defines the method.
 105   AttrNoOverride           = (1 << 13), //    X  |          |    X    //
 106                                         //       |          |         //
 107   // Indicates that this method should always be cloned when inherited.
 108   AttrClone                = (1 << 14), //       |          |    X    //
 109                                         //       |          |         //
 110   // Indicates that a function is a builtin that takes variadic arguments,
 111   // where the arguments are either by ref or optionally by ref.  It is
 112   // equivalent to ClassInfo's (RefVariableArguments).
 113   AttrVariadicByRef        = (1 << 15), //       |          |    X    //
 114                                         //       |          |         //
 115   // Indicates that a function may need to use a VarEnv or varargs (i.e.,
 116   // extraArgs) at runtime.  If the debugger is enabled, all functions
 117   // must be treated as having this flag.
 118   AttrMayUseVV             = (1 << 16), //       |          |    X    //
 119                                         //       |          |         //
 120   // Indicates that the function or class can be loaded once and then persisted
 121   // across all requests.               //       |          |         //
 122   AttrPersistent           = (1 << 17), //    X  |          |    X    //
 123                                         //       |          |         //
 124   // Indicates that this property cannot be initialized on an ObjectData by
 125   // simply memcpy-ing from the initializer vector.         |         //
 126   AttrDeepInit             = (1 << 18), //       |    X     |         //
 127                                         //       |          |         //
 128   // This HNI method takes an additional "func_num_args()" value at the
 129   // beginning of its signature (after Class*/ObjectData* for methods)
 130   AttrNumArgs              = (1 << 18), //       |          |    X    //
 131                                         //       |          |         //
 132   // Set on functions to mark them as hot during PGO profiling.       //
 133   AttrHot                  = (1 << 19), //       |          |    X    //
 134                                         //       |          |         //
 135   // Set on all builtin functions, whether PHP or C++.
 136   AttrBuiltin              = (1 << 20), //    X  |          |    X    //
 137                                         //       |          |         //
 138   // Set on all properties that should not be serialized (e.g.
 139   // <<__Memoize> caches).  Reuses the AttrBuiltin bit.
 140   AttrNoSerialize          = (1 << 20), //       |    X     |         //
 141                                         //       |          |         //
 142   // Set on all functions which take at least one inout parameter. Also implies
 143   // that the function takes no parameters by reference.
 144   AttrTakesInOutParams     = (1 << 21), //       |          |    X    //
 145                                         //       |          |         //
 146   // Set on properties to indicate they can't be changed after construction
 147   // and on classes to indicate that all that class' properties are immutable.
 148   AttrIsImmutable          = (1 << 21), //    X  |    X     |         //
 149                                         //       |          |         //
 150   // Set on classes to indicate that they have at least one immutable property.
 151   AttrHasImmutable         = (1 << 22), //    X  |          |         //
 152                                         //       |          |         //
 153   // Indicates that the frame should be ignored when searching for context
 154   // (e.g., array_map evalutates its callback in the context of the caller).
 155   AttrSkipFrame            = (1 << 22), //       |          |    X    //
 156                                         //       |          |         //
 157   // Indicates that the function might read from the caller's frame. Only
 158   // allowed for builtins.
 159   AttrReadsCallerFrame     = (1 << 23), //       |          |    X    //
 160                                         //       |          |         //
 161   // Indicates that the function might write to the caller's frame. Only allowed
 162   // for builtins.
 163   AttrWritesCallerFrame    = (1 << 24), //       |          |    X    //
 164                                         //       |          |         //
 165   // Is this a (non-static) method that *must* have a non-null this?  //
 166   AttrRequiresThis         = (1 << 25), //       |          |    X    //
 167                                         //       |          |         //
 168   // Indicates that this function can be constant-folded if it is called with
 169   // all constant arguments.            //       |          |         //
 170   AttrIsFoldable           = (1 << 26), //       |          |    X    //
 171                                         //       |          |         //
 172   // Indicates that this function cannot be called with FCallBuiltin because it
 173   // requires an ActRec argument.       //       |          |         //
 174   AttrNoFCallBuiltin       = (1 << 27), //       |          |    X    //
 175                                         //       |          |         //
 176   // Does this function have a `...' parameter?  |          |         //
 177   AttrVariadicParam        = (1 << 28), //       |          |    X    //
 178                                         //       |          |         //
 179   // Indicates that a function will attempt to coerce parameters to the correct
 180   // type.  This isn't the same as casting---for example, a string can be cast
 181   // to an array, but cannot be coerced to an array.  If it fails, the function
 182   // returns either false or null, depending on the mode.  This behavior is
 183   // common in PHP5 builtins.           //       |          |         //
 184   AttrParamCoerceModeFalse = (1 << 29), //       |          |    X    //
 185   AttrParamCoerceModeNull  = (1 << 30), //       |          |    X    //
 186   // Indicates that this function wraps either a function taking inout or ref
 187   // parameters.                        //       |          |         //
 188   AttrIsInOutWrapper       = (1 << 31), //       |          |    X    //
 189 };
 190
 191 constexpr Attr operator|(Attr a, Attr b) { return Attr((int)a | (int)b); }
 192
 193 inline Attr& operator|=(Attr& a, const Attr& b) {
 194   return (a = Attr((int)a | (int)b));
 195 }
 196
 197 inline void attrSetter(Attr& attrs, bool set, Attr what) {
 198   if (set) {
 199     attrs |= what;
 200   } else {
 201     attrs = Attr(attrs & ~what);
 202   }
 203 }
 204
 205 inline const char* attrToVisibilityStr(Attr attr) {
 206   return (attr & AttrPrivate)   ? "private"   :
 207          (attr & AttrProtected) ? "protected" : "public";
 208 }
 209
 210 ///////////////////////////////////////////////////////////////////////////////
 211 }
 212
 213 #endif // incl_HPHP_ATTR_H_