hphp/runtime/vm/type-constraint.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_TYPE_CONSTRAINT_H_
  18 #define incl_HPHP_TYPE_CONSTRAINT_H_
  19
  20 #include "hphp/runtime/base/annot-type.h"
  21 #include "hphp/runtime/vm/named-entity.h"
  22 #include "hphp/runtime/vm/type-profile.h"
  23
  24 #include "hphp/util/functional.h"
  25
  26 #include <functional>
  27 #include <string>
  28
  29 namespace HPHP {
  30 struct Func;
  31 struct StringData;
  32 }
  33
  34 namespace HPHP {
  35
  36 //////////////////////////////////////////////////////////////////////
  37
  38 /*
  39  * TypeConstraint represents the metadata required to check a PHP
  40  * function or method parameter typehint at runtime.
  41  */
  42 struct TypeConstraint {
  43   enum Flags : uint8_t {
  44     NoFlags = 0x0,
  45
  46     /*
  47      * Nullable type hints check they are either the specified type,
  48      * or null.
  49      */
  50     Nullable = 0x1,
  51
  52     /*
  53      * This flag indicates either EnableHipHopSyntax was true, or the
  54      * type came from a <?hh file and EnableHipHopSyntax was false.
  55      */
  56     HHType = 0x2,
  57
  58     /*
  59      * Extended hints are hints that do not apply to normal, vanilla
  60      * php.  For example "?Foo".
  61      */
  62     ExtendedHint = 0x4,
  63
  64     /*
  65      * Indicates that a type constraint is a type variable. For example,
  66      * the constraint on $x is a TypeVar.
  67      * class Foo<T> {
  68      *   public function bar(T $x) { ... }
  69      * }
  70      */
  71     TypeVar = 0x8,
  72
  73     /*
  74      * Soft type hints: triggers warning, but never fatals
  75      * E.g. "@int"
  76      */
  77     Soft = 0x10,
  78
  79     /*
  80      * Indicates a type constraint is a type constant, which is similar to a
  81      * type alias defined inside a class. For instance, the constraint on $x
  82      * is a TypeConstant:
  83      *
  84      * class Foo {
  85      *   const type T = int;
  86      *   public function bar(Foo::T $x) { ... }
  87      * }
  88      */
  89     TypeConstant = 0x20,
  90
  91     /*
  92      * Indicates that a Object type-constraint was resolved by hhbbc,
  93      * and the actual type is in m_type. When set, Object is guaranteed
  94      * to be an object, not a type-alias.
  95      */
  96     Resolved = 0x40
  97   };
  98
  99   /*
 100    * Special type constraints use a "Type", instead of just
 101    * underlyingDataType().
 102    *
 103    * See underlyingDataType().
 104    */
 105   using Type = AnnotType;
 106   using MetaType = AnnotMetaType;
 107
 108   static const int32_t ReturnId = -1;
 109
 110   TypeConstraint()
 111     : m_flags(NoFlags)
 112     , m_typeName(nullptr)
 113     , m_namedEntity(nullptr)
 114   {
 115     init();
 116   }
 117
 118   TypeConstraint(const StringData* typeName, Flags flags)
 119     : m_flags(flags)
 120     , m_typeName(typeName)
 121     , m_namedEntity(nullptr)
 122   {
 123     assert(!(flags & Flags::Resolved));
 124     init();
 125   }
 126
 127   template<class SerDe>
 128   void serde(SerDe& sd) {
 129     sd(m_typeName)
 130       (m_flags)
 131       ;
 132     if (m_flags & Flags::Resolved) {
 133       sd(m_type);
 134     }
 135     if (SerDe::deserializing) {
 136       init();
 137     }
 138   }
 139
 140   TypeConstraint(const TypeConstraint&) = default;
 141   TypeConstraint& operator=(const TypeConstraint&) = default;
 142
 143   void resolveType(AnnotType t, bool nullable) {
 144     assert(m_type == AnnotType::Object);
 145     assert(t != AnnotType::Object);
 146     auto flags = m_flags | Flags::Resolved;
 147     if (nullable) flags |= Flags::Nullable;
 148     m_flags = static_cast<Flags>(flags);
 149     m_type = t;
 150   }
 151
 152   /*
 153    * Returns: whether this constraint implies any runtime checking at
 154    * all.  If this function returns false, it means the
 155    * VerifyParamType would be a no-op.
 156    */
 157   bool hasConstraint() const { return m_typeName; }
 158
 159   /*
 160    * Read access to various members.
 161    */
 162   const StringData* typeName() const { return m_typeName; }
 163   const NamedEntity* namedEntity() const { return m_namedEntity; }
 164   Flags flags() const { return m_flags; }
 165
 166   /*
 167    * Access to the "meta type" for this TypeConstraint.
 168    */
 169   MetaType metaType() const { return getAnnotMetaType(m_type); }
 170
 171   /*
 172    * Returns the underlying DataType for this TypeConstraint.
 173    */
 174   MaybeDataType underlyingDataType() const {
 175     auto const dt = getAnnotDataType(m_type);
 176     return (dt != KindOfUninit || isPrecise())
 177       ? MaybeDataType(dt)
 178       : folly::none;
 179   }
 180
 181   /*
 182    * Returns the underlying DataType for this TypeConstraint,
 183    * chasing down type aliases.
 184    */
 185   MaybeDataType underlyingDataTypeResolved() const;
 186
 187   /*
 188    * Predicates for various properties of the type constraint.
 189    */
 190   bool isNullable() const { return m_flags & Nullable; }
 191   bool isSoft()     const { return m_flags & Soft; }
 192   bool isHHType()   const { return m_flags & HHType; }
 193   bool isExtended() const { return m_flags & ExtendedHint; }
 194   bool isTypeVar()  const { return m_flags & TypeVar; }
 195   bool isTypeConstant() const { return m_flags & TypeConstant; }
 196   bool isResolved() const { return m_flags & Resolved; }
 197
 198   bool isPrecise()  const { return metaType() == MetaType::Precise; }
 199   bool isMixed()    const { return m_type == Type::Mixed; }
 200   bool isSelf()     const { return m_type == Type::Self; }
 201   bool isThis()     const { return m_type == Type::This; }
 202   bool isParent()   const { return m_type == Type::Parent; }
 203   bool isCallable() const { return m_type == Type::Callable; }
 204   bool isNumber()   const { return m_type == Type::Number; }
 205   bool isArrayKey() const { return m_type == Type::ArrayKey; }
 206
 207   bool isArray()    const { return m_type == Type::Array; }
 208   bool isDict()     const { return m_type == Type::Dict; }
 209   bool isVec()      const { return m_type == Type::Vec; }
 210   bool isKeyset()   const { return m_type == Type::Keyset; }
 211
 212   bool isObject()   const { return m_type == Type::Object; }
 213
 214   AnnotType type()  const { return m_type; }
 215
 216   /*
 217    * A string representation of this type constraint.
 218    */
 219   std::string fullName() const {
 220     std::string name;
 221     if (isSoft()) {
 222       name += '@';
 223     }
 224     if (isNullable() && isExtended()) {
 225       name += '?';
 226     }
 227     name += m_typeName->data();
 228     if (isNullable() && !isExtended()) {
 229       name += " (defaulted to null)";
 230     }
 231     return name;
 232   }
 233
 234   std::string displayName(const Func* func = nullptr, bool extra = false) const;
 235
 236   /*
 237    * Returns: whether two TypeConstraints are compatible, in the sense
 238    * required for PHP inheritance where a method with parameter
 239    * typehints is overridden.
 240    */
 241   bool compat(const TypeConstraint& other) const;
 242
 243   // General check for any constraint.
 244   bool check(TypedValue* tv, const Func* func) const;
 245
 246   bool checkTypeAliasObj(const Class* cls) const;
 247   bool checkTypeAliasNonObj(const TypedValue* tv) const;
 248
 249   // NB: will throw if the check fails.
 250   void verifyParam(TypedValue* tv, const Func* func, int paramNum,
 251                    bool useStrictTypes = true) const {
 252     if (UNLIKELY(!check(tv, func))) {
 253       verifyParamFail(func, tv, paramNum, useStrictTypes);
 254     }
 255   }
 256   void verifyReturn(TypedValue* tv, const Func* func,
 257                     bool useStrictTypes = true) const {
 258     if (UNLIKELY(!check(tv, func))) {
 259       verifyReturnFail(func, tv, useStrictTypes);
 260     }
 261   }
 262
 263   // Can not be private; used by the translator.
 264   void selfToClass(const Func* func, const Class **cls) const;
 265   void parentToClass(const Func* func, const Class **cls) const;
 266   void verifyFail(const Func* func, TypedValue* tv, int id,
 267                   bool useStrictTypes) const;
 268   void verifyParamFail(const Func* func, TypedValue* tv,
 269                        int paramNum, bool useStrictTypes = true) const;
 270   void verifyReturnFail(const Func* func, TypedValue* tv,
 271                         bool useStrictTypes = true) const {
 272     verifyFail(func, tv, ReturnId, useStrictTypes);
 273   }
 274
 275 private:
 276   void init();
 277   void selfToTypeName(const Func* func, const StringData **typeName) const;
 278   void parentToTypeName(const Func* func, const StringData **typeName) const;
 279
 280 private:
 281   // m_type represents the type to check on.  We don't know whether a
 282   // bare name is a class/interface name or a type alias or an enum,
 283   // so when this is set to Type::Object we may have to resolve a type
 284   // alias or enum and test for a different DataType (see annotCompat()
 285   // for details).
 286   Type m_type;
 287   Flags m_flags;
 288   LowStringPtr m_typeName;
 289   LowPtr<const NamedEntity> m_namedEntity;
 290 };
 291
 292 //////////////////////////////////////////////////////////////////////
 293
 294 inline TypeConstraint::Flags
 295 operator|(TypeConstraint::Flags a, TypeConstraint::Flags b) {
 296   return TypeConstraint::Flags(static_cast<int>(a) | static_cast<int>(b));
 297 }
 298
 299 //////////////////////////////////////////////////////////////////////
 300
 301 /*
 302  * Its possible to use type constraints on function parameters to devise better
 303  * memoization key generation schemes. For example, if we know the
 304  * type-constraint limits the parameter to only ever being an integer or string,
 305  * then the memoization key scheme can just be the identity. This is because
 306  * integers and strings won't collide with each other, and we know it won't ever
 307  * be anything else. Without such a constraint, the string would need escaping.
 308  *
 309  * This function takes a type-constraint and returns the suitable "memo-key
 310  * constraint" if it corresponds to one. Note: HHBBC, the interpreter, and the
 311  * JIT all need to agree exactly on the scheme for each constraint. It is the
 312  * caller's responsibility to actually verify that type-hints are being
 313  * enforced. If they are not, then none of this information can be used.
 314  */
 315 enum class MemoKeyConstraint {
 316   Null,
 317   Int,
 318   IntOrNull,
 319   Bool,
 320   BoolOrNull,
 321   Str,
 322   StrOrNull,
 323   IntOrStr,
 324   None
 325 };
 326 MemoKeyConstraint memoKeyConstraintFromTC(const TypeConstraint&);
 327
 328 }
 329
 330 #endif