Merge "stagefright/foundation: add TypeTraits.h and Flagged.h"

/*

 * Copyright (C) 2016 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

#ifndef STAGEFRIGHT_FOUNDATION_FLAGGED_H_

#define STAGEFRIGHT_FOUNDATION_FLAGGED_H_

#include <media/stagefright/foundation/TypeTraits.h>

namespace android {

/**

 * Flagged<T, Flag> is basically a specialized std::pair<Flag, T> that automatically optimizes out

 * the flag if the wrapped type T is already flagged and we can combine the outer and inner flags.

 *

 * Flags can be queried/manipulated via flags() an setFlags(Flags). The wrapped value can be

 * accessed via get(). This template is meant to be inherited by other utility/wrapper classes

 * that need to store integral information along with the value.

 *

 * Users must specify the used bits (MASK) in the flags. Flag getters and setters will enforce this

 * mask. _Flagged_helper::minMask<Flag> is provided to easily calculate a mask for a max value.

 *

 * E.g. adding a safe flag can be achieved like this:

 *

 *

 * enum SafeFlags : uint32_t {

 *   kUnsafe,

 *   kSafe,

 *   kSafeMask = _Flagged_helper::minMask(kSafe),

 * };

 * typedef Flagged<int32_t, SafeFlags, kSafeMask> safeInt32;

 *

 * safeInt32 a;

 * a.setFlags(kSafe);

 * a.get() = 15;

 * EXPECT_EQ(a.flags(), kSafe);

 * EXPECT_EQ(a.get(), 15);

 *

 *

 * Flagged also supports lazy or calculated wrapping of already flagged types. Lazy wrapping is

 * provided automatically (flags are automatically shared if possible, e.g. mask is shifted

 * automatically to not overlap with used bits of the wrapped type's flags, and fall back to

 * unshared version of the template.):

 *

 * enum OriginFlags : uint32_t {

 *   kUnknown,

 *   kConst,

 *   kCalculated,

 *   kComponent,

 *   kApplication,

 *   kFile,

 *   kBinder,

 *   kOriginMask = _Flagged_helper::minMask(kBinder),

 * };

 * typedef Flagged<safeInt32, OriginFlags, kOriginMask>

 *          trackedSafeInt32;

 *

 * static_assert(sizeof(trackedSafeInt32) == sizeof(safeInt32), "");

 *

 * trackedSafeInt32 b(kConst, kSafe, 1);

 * EXPECT_EQ(b.flags(), kConst);

 * EXPECT_EQ(b.get().flags(), kSafe);

 * EXPECT_EQ(b.get().get(), 1);

 * b.setFlags(kCalculated);

 * b.get().setFlags(overflow ? kUnsafe : kSafe);

 *

 * One can also choose to share some flag-bits with the wrapped class:

 *

 * enum ValidatedFlags : uint32_t {

 *   kUnsafeV = kUnsafe,

 *   kSafeV = kSafe,

 *   kValidated = kSafe | 2,

 *   kSharedMaskV = kSafeMask,

 *   kValidatedMask = _Flagged_helper::minMask(kValidated),

 * };

 * typedef Flagged<safeInt32, ValidatedFlags, kValidatedMask, kSharedMaskV> validatedInt32;

 *

 * validatedInt32 v(kUnsafeV, kSafe, 10);

 * EXPECT_EQ(v.flags(), kUnsafeV);

 * EXPECT_EQ(v.get().flags(), kUnsafe);  // !kUnsafeV overrides kSafe

 * EXPECT_EQ(v.get().get(), 10);

 * v.setFlags(kValidated);

 * EXPECT_EQ(v.flags(), kValidated);

 * EXPECT_EQ(v.get().flags(), kSafe);

 * v.get().setFlags(kUnsafe);

 * EXPECT_EQ(v.flags(), 2);  // NOTE: sharing masks with enums allows strange situations to occur

 */

/**

 * Helper class for Flagged support. Encapsulates common utilities used by all

 * templated classes.

 */

struct _Flagged_helper {

    /**

     * Calculates the value with a given number of top-most bits set.

     *

     * This method may be called with a signed flag.

     *

     * \param num number of bits to set. This must be between 0 and the number of bits in Flag.

     *

     * \return the value where only the given number of top-most bits are set.

     */

    template<typename Flag>

    static constexpr Flag topBits(int num) {

        return Flag(num > 0 ?

                    ~((Flag(1) << (sizeof(Flag) * 8 - is_signed_integral<Flag>::value - num)) - 1) :

                    0);

    }

    /**

     * Calculates the minimum mask required to cover a value. Used with the maximum enum value for

     * an unsigned flag.

     *

     * \param maxValue maximum value to cover

     * \param shift DO NO USE. used internally

     *

     * \return mask that can be used that covers the maximum value.

     */

    template<typename Flag>

    static constexpr Flag minMask(Flag maxValue, int shift=sizeof(Flag) * 4) {

        static_assert(is_unsigned_integral<Flag>::value,

                      "this method only makes sense for unsigned flags");

        return shift ? minMask<Flag>(Flag(maxValue | (maxValue >> shift)), shift >> 1) : maxValue;

    }

    /**

     * Returns a value left-shifted by an argument as a potential constexpr.

     *

     * This method helps around the C-language limitation, when left-shift of a negative value with

     * even 0 cannot be a constexpr.

     *

     * \param value value to shift

     * \param shift amount of shift

     * \returns the shifted value as an integral type

     */

    template<typename Flag, typename IntFlag = typename underlying_integral_type<Flag>::type>

    static constexpr IntFlag lshift(Flag value, int shift) {

        return shift ? value << shift : value;

    }

private:

    /**

     * Determines whether mask can be combined with base-mask for a given left shift.

     *

     * \param mask desired mask

     * \param baseMask mask used by T or 0 if T is not flagged by Flag

     * \param sharedMask desired shared mask (if this is non-0, this must be mask & baseMask)

     * \param shift desired left shift to be used for mask

     * \param baseShift left shift used by T or 0 if T is not flagged by Flag

     * \param effectiveMask effective mask used by T or 0 if T is not flagged by Flag

     *

     * \return bool whether mask can be combined with baseMask using the desired values.

     */

    template<typename Flag, typename IntFlag=typename underlying_integral_type<Flag>::type>

    static constexpr bool canCombine(

            Flag mask, IntFlag baseMask, Flag sharedMask, int shift,

            int baseShift, IntFlag effectiveMask) {

        return

            // verify that shift is valid and mask can be shifted

            shift >= 0 && (mask & topBits<Flag>(shift)) == 0 &&

            // verify that base mask is part of effective mask (sanity check on arguments)

            (baseMask & ~(effectiveMask >> baseShift)) == 0 &&

            // if sharing masks, shift must be the base's shift.

            // verify that shared mask is the overlap of base mask and mask

            (sharedMask ?

                    ((sharedMask ^ (baseMask & mask)) == 0 &&

                     shift == baseShift) :

            // otherwise, verify that there is no overlap between mask and base's effective mask

                    (mask & (effectiveMask >> shift)) == 0);

    }

    /**

     * Calculates the minimum (left) shift required to combine a mask with the mask of an

     * underlying type (T, also flagged by Flag).

     *

     * \param mask desired mask

     * \param baseMask mask used by T or 0 if T is not flagged by Flag

     * \param sharedMask desired shared mask (if this is non-0, this must be mask & baseMask)

     * \param baseShift left shift used by T

     * \param effectiveMask effective mask used by T

     *

     * \return a non-negative minimum left shift value if mask can be combined with baseMask,

     *         or -1 if the masks cannot be combined. -2 if the input is invalid.

     */

    template<typename Flag,

             typename IntFlag = typename underlying_integral_type<Flag>::type>

    static constexpr int getShift(

            Flag mask, IntFlag baseMask, Flag sharedMask, int baseShift, IntFlag effectiveMask) {

        return

            // baseMask must be part of the effective mask

            (baseMask & ~(effectiveMask >> baseShift)) ? -2 :

            // if sharing masks, shift must be base's shift. verify that shared mask is part of

            // base mask and mask, and that desired mask still fits with base's shift value

            sharedMask ?

                    (canCombine(mask, baseMask, sharedMask, baseShift /* shift */,

                                baseShift, effectiveMask) ? baseShift : -1) :

            // otherwise, see if 0-shift works

            ((mask & effectiveMask) == 0) ? 0 :

            // otherwise, verify that mask can be shifted up

            ((mask & topBits<Flag>(1)) || (mask < 0)) ? -1 :

            incShift(getShift(Flag(mask << 1), baseMask /* unused */, sharedMask /* 0 */,

                              baseShift /* unused */, effectiveMask));

    }

    /**

     * Helper method that increments a non-negative (shift) value.

     *

     * This method is used to make it easier to create a constexpr for getShift.

     *

     * \param shift (shift) value to increment

     *

     * \return original shift if it was negative; otherwise, the shift incremented by one.

     */

    static constexpr int incShift(int shift) {

        return shift + (shift >= 0);

    }

#ifdef FRIEND_TEST

    FRIEND_TEST(FlaggedTest, _Flagged_helper_Test);

#endif

public:

    /**

     * Base class for all Flagged<T, Flag> classes.

     *

     * \note flagged types do not have a member variable for the mask used by the type. As such,

     * they should be be cast to this base class.

     *

     * \todo can we replace this base class check with a static member check to remove possibility

     * of cast?

     */

    template<typename Flag>

    struct base {};

    /**

     * Type support utility that retrieves the mask of a class (T) if it is a type flagged by

     * Flag (e.g. Flagged<T, Flag>).

     *

     * \note This retrieves 0 if T is a flagged class, that is not flagged by Flag or an equivalent

     * underlying type.

     *

     * Generic implementation for a non-flagged class.

     */

    template<

        typename T, typename Flag,

        bool=std::is_base_of<base<typename underlying_integral_type<Flag>::type>, T>::value>

    struct mask_of {

        using IntFlag = typename underlying_integral_type<Flag>::type;

        static constexpr IntFlag value = Flag(0); ///< mask of a potentially flagged class

        static constexpr int shift = 0; ///<left shift of flags in a potentially flagged class

        static constexpr IntFlag effective_value = IntFlag(0); ///<effective mask of flagged class

    };

    /**

     * Type support utility that calculates the minimum (left) shift required to combine a mask

     * with the mask of an underlying type T also flagged by Flag.

     *

     * \note if T is not flagged, not flagged by Flag, or the masks cannot be combined due to

     * incorrect sharing or the flags not having enough bits, the minimum is -1.

     *

     * \param MASK desired mask

     * \param SHARED_MASK desired shared mask (if this is non-0, T must be an type flagged by

     *        Flag with a mask that has exactly these bits common with MASK)

     */

    template<typename T, typename Flag, Flag MASK, Flag SHARED_MASK>

    struct min_shift {

        /// minimum (left) shift required, or -1 if masks cannot be combined

        static constexpr int value =

            getShift(MASK, mask_of<T, Flag>::value, SHARED_MASK,

                     mask_of<T, Flag>::shift, mask_of<T, Flag>::effective_value);

    };

    /**

     * Type support utility that calculates whether the flags of T can be combined with MASK.

     *

     * \param MASK desired mask

     * \param SHARED_MASK desired shared mask (if this is non-0, T MUST be an type flagged by

     *        Flag with a mask that has exactly these bits common with MASK)

     */

    template<

            typename T, typename Flag, Flag MASK,

            Flag SHARED_MASK=Flag(0),

            int SHIFT=min_shift<T, Flag, MASK, SHARED_MASK>::value>

    struct can_combine {

        using IntFlag = typename underlying_integral_type<Flag>::type;

        /// true if this mask can be combined with T's existing flag. false otherwise.

        static constexpr bool value =

                std::is_base_of<base<IntFlag>, T>::value

                        && canCombine(MASK, mask_of<T, Flag>::value, SHARED_MASK, SHIFT,

                                      mask_of<T, Flag>::shift, mask_of<T, Flag>::effective_value);

    };

};

/**

 * Template specialization for the case when T is flagged by Flag or a compatible type.

 */

template<typename T, typename Flag>

struct _Flagged_helper::mask_of<T, Flag, true> {

    using IntType = typename underlying_integral_type<Flag>::type;

    static constexpr IntType value = T::sFlagMask;

    static constexpr int shift = T::sFlagShift;

    static constexpr IntType effective_value = T::sEffectiveMask;

};

/**

 * Main Flagged template that adds flags to an object of another type (in essence, creates a pair)

 *

 * Flag must be an integral type (enums are allowed).

 *

 * \note We could make SHARED_MASK be a boolean as it must be either 0 or MASK & base's mask, but we

 * want it to be spelled out for safety.

 *

 * \param T type of object wrapped

 * \param Flag type of flag

 * \param MASK mask for the bits used in flag (before any shift)

 * \param SHARED_MASK optional mask to be shared with T (if this is not zero, SHIFT must be 0, and

 *        it must equal to MASK & T's mask)

 * \param SHIFT optional left shift for MASK to combine with T's mask (or -1, if masks should not

 *        be combined.)

 */

template<

        typename T, typename Flag, Flag MASK, Flag SHARED_MASK=(Flag)0,

        int SHIFT=_Flagged_helper::min_shift<T, Flag, MASK, SHARED_MASK>::value,

        typename IntFlag=typename underlying_integral_type<Flag>::type,

        bool=_Flagged_helper::can_combine<T, IntFlag, MASK, SHARED_MASK, SHIFT>::value>

class Flagged : public _Flagged_helper::base<IntFlag> {

    static_assert(SHARED_MASK == 0,

                  "shared mask can only be used with common flag types "

                  "and must be part of mask and mask of base type");

    static_assert((_Flagged_helper::topBits<Flag>(SHIFT) & MASK) == 0, "SHIFT overflows MASK");

    static constexpr Flag sFlagMask = MASK;  ///< the mask

    static constexpr int sFlagShift = SHIFT > 0 ? SHIFT : 0; ///< the left shift applied to flags

    friend struct _Flagged_helper;

#ifdef FRIEND_TEST

    static constexpr bool sFlagCombined = false;

    FRIEND_TEST(FlaggedTest, _Flagged_helper_Test);

#endif

    T       mValue; ///< wrapped value

    IntFlag mFlags; ///< flags

protected:

    /// The effective combined mask used by this class and any wrapped classes if the flags are

    /// combined.

    static constexpr IntFlag sEffectiveMask = _Flagged_helper::lshift(MASK, sFlagShift);

    /**

     * Helper method used by subsequent flagged wrappers to query flags. Returns the

     * flags for a particular mask and left shift.

     *

     * \param mask bitmask to use

     * \param shift left shifts to use

     *

     * \return the requested flags

     */

    inline constexpr IntFlag getFlagsHelper(IntFlag mask, int shift) const {

        return (mFlags >> shift) & mask;

    }

    /**

     * Helper method used by subsequent flagged wrappers to apply combined flags. Sets the flags

     * in the bitmask using a particulare left shift.

     *

     * \param mask bitmask to use

     * \param shift left shifts to use

     * \param flags flags to update (any flags within the bitmask are updated to their value in this

     *        argument)

     */

    inline void setFlagsHelper(IntFlag mask, int shift, IntFlag flags) {

        mFlags = Flag((mFlags & ~(mask << shift)) | ((flags & mask) << shift));

    }

public:

    /**

     * Wrapper around base class constructor. These take the flags as their first

     * argument and pass the rest of the arguments to the base class constructor.

     *

     * \param flags initial flags

     */

    template<typename ...Args>

    constexpr Flagged(Flag flags, Args... args)

        : mValue(std::forward<Args>(args)...),

          mFlags(Flag(_Flagged_helper::lshift(flags & sFlagMask, sFlagShift))) { }

    /** Gets the wrapped value as const. */

    inline constexpr const T &get() const { return mValue; }

    /** Gets the wrapped value. */

    inline T &get() { return mValue; }

    /** Gets the flags. */

    constexpr Flag flags() const {

        return Flag(getFlagsHelper(sFlagMask, sFlagShift));

    }

    /** Sets the flags. */

    void setFlags(Flag flags) {

        setFlagsHelper(sFlagMask, sFlagShift, flags);

    }

};

/*

 * TRICKY: we cannot implement the specialization as:

 *

 * class Flagged : base<Flag> {

 *    T value;

 * };

 *

 * Because T also inherits from base<Flag> and this runs into a compiler bug where

 * sizeof(Flagged) > sizeof(T).

 *

 * Instead, we must inherit directly from the wrapped class

 *

 */

#if 0

template<

        typename T, typename Flag, Flag MASK, Flag SHARED_MASK, int SHIFT>

class Flagged<T, Flag, MASK, SHARED_MASK, SHIFT, true> : public _Flagged_helper::base<Flag> {

private:

    T mValue;

};

#else

/**

 * Specialization for the case when T is derived from Flagged<U, Flag> and flags can be combined.

 */

template<

        typename T, typename Flag, Flag MASK, Flag SHARED_MASK, int SHIFT, typename IntFlag>

class Flagged<T, Flag, MASK, SHARED_MASK, SHIFT, IntFlag, true> : private T {

    static_assert(is_integral_or_enum<Flag>::value, "flag must be integer or enum");

    static_assert(SHARED_MASK == 0 || SHIFT == 0, "cannot overlap masks when using SHIFT");

    static_assert((SHARED_MASK & ~MASK) == 0, "shared mask must be part of the mask");

    static_assert((SHARED_MASK & ~T::sEffectiveMask) == 0,

                  "shared mask must be part of the base mask");

    static_assert(SHARED_MASK == 0 || (~SHARED_MASK & (MASK & T::sEffectiveMask)) == 0,

                  "mask and base mask can only overlap in shared mask");

    static constexpr Flag sFlagMask = MASK;  ///< the mask

    static constexpr int sFlagShift = SHIFT;  ///< the left shift applied to the flags

#ifdef FRIEND_TEST

    const static bool sFlagCombined = true;

    FRIEND_TEST(FlaggedTest, _Flagged_helper_Test);

#endif

protected:

    /// The effective combined mask used by this class and any wrapped classes if the flags are

    /// combined.

    static constexpr IntFlag sEffectiveMask = Flag((MASK << SHIFT) | T::sEffectiveMask);

    friend struct _Flagged_helper;

public:

    /**

     * Wrapper around base class constructor. These take the flags as their first

     * argument and pass the rest of the arguments to the base class constructor.

     *

     * \param flags initial flags

     */

    template<typename ...Args>

    constexpr Flagged(Flag flags, Args... args)

        : T(std::forward<Args>(args)...) {

        // we construct the base class first and apply the flags afterwards as

        // base class may not have a constructor that takes flags even if it is derived from

        // Flagged<U, Flag>

        setFlags(flags);

    }

    /** Gets the wrapped value as const. */

    inline constexpr T &get() const { return *this; }

    /** Gets the wrapped value. */

    inline T &get() { return *this; }

    /** Gets the flags. */

    Flag constexpr flags() const {

        return Flag(this->getFlagsHelper(sFlagMask, sFlagShift));

    }

    /** Sets the flags. */

    void setFlags(Flag flags) {

        this->setFlagsHelper(sFlagMask, sFlagShift, flags);

    }

};

#endif

}  // namespace android

#endif  // STAGEFRIGHT_FOUNDATION_FLAGGED_H_

/*

 * Copyright (C) 2016 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

#ifndef STAGEFRIGHT_FOUNDATION_TYPE_TRAITS_H_

#define STAGEFRIGHT_FOUNDATION_TYPE_TRAITS_H_

#include <type_traits>

namespace android {

/**

 * std::is_signed, is_unsigned and is_integral does not consider enums even though the standard

 * considers them integral. Create modified versions of these here. Also create a wrapper around

 * std::underlying_type that does not require checking if the type is an enum.

 */

/**

 * Type support utility class to check if a type is an integral type or an enum.

 */

template<typename T>

struct is_integral_or_enum

    : std::integral_constant<bool, std::is_integral<T>::value || std::is_enum<T>::value> { };

/**

 * Type support utility class to get the underlying std::is_integral supported type for a type.

 * This returns the underlying type for enums, and the same type for types covered by

 * std::is_integral.

 *

 * This is also used as a conditional to return an alternate type if the template param is not

 * an integral or enum type (as in underlying_integral_type<T, TypeIfNotEnumOrIntegral>::type).

 */

template<typename T,

        typename U=typename std::enable_if<is_integral_or_enum<T>::value>::type,

        bool=std::is_enum<T>::value,

        bool=std::is_integral<T>::value>

struct underlying_integral_type {

    static_assert(!std::is_enum<T>::value, "T should not be enum here");

    static_assert(!std::is_integral<T>::value, "T should not be integral here");

    typedef U type;

};

/** Specialization for enums. */

template<typename T, typename U>

struct underlying_integral_type<T, U, true, false> {

    static_assert(std::is_enum<T>::value, "T should be enum here");

    static_assert(!std::is_integral<T>::value, "T should not be integral here");

    typedef typename std::underlying_type<T>::type type;

};

/** Specialization for non-enum std-integral types. */

template<typename T, typename U>

struct underlying_integral_type<T, U, false, true> {

    static_assert(!std::is_enum<T>::value, "T should not be enum here");

    static_assert(std::is_integral<T>::value, "T should be integral here");

    typedef T type;

};

/**

 * Type support utility class to check if the underlying integral type is signed.

 */

template<typename T>

struct is_signed_integral

    : std::integral_constant<bool, std::is_signed<

            typename underlying_integral_type<T, unsigned>::type>::value> { };

/**

 * Type support utility class to check if the underlying integral type is unsigned.

 */

template<typename T>

struct is_unsigned_integral

    : std::integral_constant<bool, std::is_unsigned<

            typename underlying_integral_type<T, signed>::type>::value> {

};

}  // namespace android

#endif  // STAGEFRIGHT_FOUNDATION_TYPE_TRAITS_H_

# Build the unit tests.

LOCAL_PATH:= $(call my-dir)

include $(CLEAR_VARS)

LOCAL_ADDITIONAL_DEPENDENCIES := $(LOCAL_PATH)/Android.mk

LOCAL_MODULE := sf_foundation_test

LOCAL_MODULE_TAGS := tests

LOCAL_SRC_FILES := \

	Flagged_test.cpp \

	TypeTraits_test.cpp \

	Utils_test.cpp \

LOCAL_SHARED_LIBRARIES := \

	libstagefright_foundation \

LOCAL_C_INCLUDES := \

	frameworks/av/include \

LOCAL_CFLAGS += -Werror -Wall

LOCAL_CLANG := true

include $(BUILD_NATIVE_TEST)

# Include subdirectory makefiles

# ============================================================

# If we're building with ONE_SHOT_MAKEFILE (mm, mmm), then what the framework

# team really wants is to build the stuff defined by this makefile.

ifeq (,$(ONE_SHOT_MAKEFILE))

include $(call first-makefiles-under,$(LOCAL_PATH))

endif