concurrent_vector.h

C语言库函数的原型,有用的拿去

    /// <param name="_Begin">
    ///     Position of the first element in the range of elements to be copied.
    /// </param>
    /// <param name="_End">
    ///     Position of the first element beyond the range of elements to be copied.
    /// </param>
    /// <param name="_Al">
    ///     The allocator class to use with this object.
    /// </param>
    /// <remarks>
    ///     All constructors store an allocator object <paramref name="_Al"/> and initialize the vector.
    ///     <para>The first constructor specify an empty initial vector and explicitly specifies the allocator type.
    ///     to be used.</para>
    ///     <para>The second and third constructors specify a copy of the concurrent vector <paramref name="_Vector"/>.</para>
    ///     <para>The fourth constructor specifies a repetition of a specified number (<paramref name="_N"/>) of elements of the default
    ///     value for class <typeparamref name="_Ty"/>.</para>
    ///     <para>The fifth constructor specifies a repetition of (<paramref name="_N"/>) elements of value <paramref name="_Item"/>.</para>
    ///     <para>The last constructor specifies values supplied by the iterator range [<paramref name="_Begin"/>, <paramref name="_End"/>).</para>
    /// </remarks>
    /**/
    template<class _InputIterator>
    concurrent_vector(_InputIterator _Begin, _InputIterator _End, const allocator_type &_Al = allocator_type())
        : details::_Allocator_base<_Ty, _Ax>(_Al)
    {
        _My_vector_allocator_ptr = &_Internal_allocator;
        _Internal_assign(_Begin, _End, static_cast<_Is_integer_tag<std::numeric_limits<_InputIterator>::is_integer> *>(0) );
    }

    /// <summary>
    ///     Assigns the contents of another <c>concurrent_vector</c> object to this one. This method is not concurrency-safe.
    /// </summary>
    /// <param name="_Vector">
    ///     The source <c>concurrent_vector</c> object.
    /// </param>
    /// <returns>
    ///     A reference to this <c>concurrent_vector</c> object.
    /// </returns>
    /**/
    concurrent_vector& operator=( const concurrent_vector& _Vector )
    {
        if( this != &_Vector )
            _Concurrent_vector_base_v4::_Internal_assign(_Vector, sizeof(_Ty), &_Destroy_array, &_Assign_array, &_Copy_array);
        return *this;
    }

    /// <summary>
    ///     Assigns the contents of another <c>concurrent_vector</c> object to this one. This method is not concurrency-safe.
    /// </summary>
    /// <typeparam name="M">
    ///     The allocator type of the source vector.
    /// </typeparam>
    /// <param name="_Vector">
    ///     The source <c>concurrent_vector</c> object.
    /// </param>
    /// <returns>
    ///     A reference to this <c>concurrent_vector</c> object.
    /// </returns>
    /**/
    template<class M>
    concurrent_vector& operator=( const concurrent_vector<_Ty, M>& _Vector )
    {
        if( static_cast<void*>( this ) != static_cast<const void*>( &_Vector ) )
        {
            _Concurrent_vector_base_v4::_Internal_assign(_Vector._Internal_vector_base(),
                                                         sizeof(_Ty), &_Destroy_array, &_Assign_array, &_Copy_array);
        }
        return *this;
    }

    /// <summary>
    ///     Grows this concurrent vector by <paramref name="_Delta"/> elements. This method is concurrency-safe.
    /// </summary>
    /// <param name="_Delta">
    ///     The number of elements to append to the object.
    /// </param>
    /// <returns>
    ///     An iterator to first item appended.
    /// </returns>
    /// <remarks>
    ///     If <paramref name="_Item"/> is not specified, the new elements are default constructed.
    /// </remarks>
    /**/
    iterator grow_by( size_type _Delta )
    {
        return iterator(*this, _Delta ? _Internal_grow_by( _Delta, sizeof(_Ty), &_Initialize_array, NULL ) : _My_early_size);
    }

    /// <summary>
    ///     Grows this concurrent vector by <paramref name="_Delta"/> elements. This method is concurrency-safe.
    /// </summary>
    /// <param name="_Delta">
    ///     The number of elements to append to the object.
    /// </param>
    /// <param name="_Item">
    ///     The value to initialize the new elements with.
    /// </param>
    /// <returns>
    ///     An iterator to first item appended.
    /// </returns>
    /// <remarks>
    ///     If <paramref name="_Item"/> is not specified, the new elements are default constructed.
    /// </remarks>
    /**/
    iterator grow_by( size_type _Delta, const_reference _Item )
    {
        return iterator(*this, _Delta ? _Internal_grow_by( _Delta, sizeof(_Ty), &_Initialize_array_by, static_cast<const void*>(&_Item) ) : _My_early_size);
    }

    /// <summary>
    ///     Grows this concurrent vector until it has at least <paramref name="_N"/> elements. This method is concurrency-safe.
    /// </summary>
    /// <param name="_N">
    ///     The new minimum size for the <c>concurrent_vector</c> object.
    /// </param>
    /// <returns>
    ///     An iterator that points to beginning of appended sequence, or to the element at index <paramref name="_N"/> if no
    ///     elements were appended.
    /// </returns>
    /**/
    iterator grow_to_at_least( size_type _N )
    {
        size_type _M = 0;
        if( _N )
        {
            _M = _Internal_grow_to_at_least_with_result( _N, sizeof(_Ty), &_Initialize_array, NULL );
            if( _M > _N )
                _M = _N;
        }
        return iterator(*this, _M);
    };

    /// <summary>
    ///     Appends the given item to the end of the concurrent vector. This method is concurrency-safe.
    /// </summary>
    /// <param name="_Item">
    ///     The value to be appended.
    /// </param>
    /// <returns>
    ///     An iterator to item appended.
    /// </returns>
    /**/
    iterator push_back( const_reference _Item )
    {
        size_type _K;
        void *_Ptr = _Internal_push_back(sizeof(_Ty), _K);
        _Internal_loop_guide _Loop(1, _Ptr);
        _Loop._Init(&_Item);
        return iterator(*this, _K, _Ptr);
    }

    /// <summary>
    ///     Provides access to the element at the given index in the concurrent vector. This method is concurrency-safe for read operations,
    ///     and also while growing the vector, as long as the you have ensured that the value <paramref name="_Index"/> is less than
    ///     the size of the concurrent vector.
    /// </summary>
    /// <param name="_Index">
    ///     The index of the element to be retrieved.
    /// </param>
    /// <returns>
    ///     A reference to the item at the given index.
    /// </returns>
    /// <remarks>
    ///     The version of <c>operator []</c> that returns a non-<c>const</c> refernce cannot be used to concurrently write to the element
    ///     from different threads. A different synchronization object should be used to synchronize concurrent read and write operations
    ///     to the same data element.
    ///     <para>No bounds checking is performed to ensure that <paramref name="_Index"/> is a valid index into the concurrent vector.</para>
    /// </remarks>
    /**/
    reference operator[]( size_type _Index )
    {
        return _Internal_subscript(_Index);
    }

    /// <summary>
    ///     Provides read access to element at the given index in the concurrent vector. This method is concurrency-safe for read operations,
    ///     and also while growing the vector, as long as the you have ensured that the value <paramref name="_Index"/> is less than
    ///     the size of the concurrent vector.
    /// </summary>
    /// <param name="_Index">
    ///     The index of the element to be retrieved.
    /// </param>
    /// <returns>
    ///     A <c>const</c> reference to the item at the given index.
    /// </returns>
    /// <remarks>
    ///     The version of <c>operator []</c> that returns a non-<c>const</c> refernce cannot be used to concurrently write to the element
    ///     from different threads. A different synchronization object should be used to synchronize concurrent read and write operations
    ///     to the same data element.
    ///     <para>No bounds checking is performed to ensure that <paramref name="_Index"/> is a valid index into the concurrent vector.</para>
    /// </remarks>
    /**/
    const_reference operator[]( size_type _Index ) const
    {
        return _Internal_subscript(_Index);
    }

    /// <summary>
    ///     Provides access to the element at the given index in the concurrent vector. This method is concurrency-safe for read operations,
    ///     and also while growing the vector, as long as you have ensured that the value <paramref name="_Index"/> is less than
    ///     the size of the concurrent vector.
    /// </summary>
    /// <param name="_Index">
    ///     The index of the element to be retrieved.
    /// </param>
    /// <returns>
    ///     A reference to the item at the given index.
    /// </returns>
    /// <remarks>
    ///     The version of the function <c>at</c> that returns a non-<c>const</c> refernce cannot be used to concurrently write to the element
    ///     from different threads. A different synchronization object should be used to synchronize concurrent read and write operations
    ///     to the same data element.
    ///     <para>The method throws <c>out_of_range</c> if <paramref name="_Index"/> is greater than or equal to the size of the concurrent vector,
    ///     and <c>range_error</c> if the index is for a broken portion of the vector. For details on how a vector can become broken,
    ///     see <see cref="Parallel Containers and Objects"/>.</para>
    /// </remarks>
    /**/
    reference at( size_type _Index )
    {
        return _Internal_subscript_with_exceptions(_Index);
    }

    /// <summary>
    ///     Provides access to the element at the given index in the concurrent vector. This method is concurrency-safe for read operations,
    ///     and also while growing the vector, as long as you have ensured that the value <paramref name="_Index"/> is less than
    ///     the size of the concurrent vector.
    /// </summary>
    /// <param name="_Index">
    ///     The index of the element to be retrieved.
    /// </param>
    /// <returns>
    ///     A <c>const</c> reference to the item at the given index.
    /// </returns>
    /// <remarks>
    ///     The version of the function <c>at</c> that returns a non-<c>const</c> refernce cannot be used to concurrently write to the element
    ///     from different threads. A different synchronization object should be used to synchronize concurrent read and write operations
    ///     to the same data element.
    ///     <para>The method throws <c>out_of_range</c> if <paramref name="_Index"/> is greater than or equal to the size of the concurrent vector,
    ///     and <c>range_error</c> if the index is for a broken portion of the vector. For details on how a vector can become broken,
    ///     see <see cref="Parallel Containers and Objects"/>.</para>
    /// </remarks>
    /**/
    const_reference at( size_type _Index ) const
    {
        return _Internal_subscript_with_exceptions(_Index);
    }

    /// <summary>
    ///     Returns the number of elements in the concurrent vector. This method is concurrency-safe.
    /// </summary>
    /// <returns>
    ///     The number of elements in this <c>concurrent_vector</c> object.
    /// </returns>
    /// <remarks>
    ///     The returned size is guaranteed to include all elements appended by calls to the function <c>push_back</c>,
    ///     or grow operations that have completed prior to invoking this method. However, it may also include elements
    ///     that are allocated but still under construction by concurrent calls to any of the growth methods.
    /// </remarks>
    /**/
    size_type size() const
    {
        size_type _Sz = _My_early_size;
        size_type _Cp = _Internal_capacity();
        return _Cp < _Sz ? _Cp : _Sz;
    }

    /// <summary>
    ///     Tests if the concurrent vector is empty at the time this method is called. This method is concurrency-safe.
    /// </summary>
    /// <returns>
    ///     <c>true</c> if the vector was empty at the moment the function was called, <c>false</c> otherwise.
    /// </returns>
    /**/
    bool empty() const
    {
        return !_My_early_size;
    }

    /// <summary>
    ///     Returns the maximum size to which the concurrent vector can grow without having to allocate more memory.
    ///     This method is concurrency-safe.
    /// </summary>
    /// <returns>
    ///     The maximum size to which the concurrent bector can grow without having to allocate more memory.
    /// </returns>
    /// <remarks>
    ///     Unlike an STL <c>vector</c>, a <c>concurrent_vector</c> object does not move existing elements if it allocates more memory.
    /// </remarks>
    /**/
    size_type capacity() const
    {
        return _Internal_capacity();
    }

    /// <summary>
    ///     Allocates enough space to grow the concurrent vector to size <paramref name="_N"/> without having to allocate more memory later.
    ///     This method is not concurrency-safe.
    /// </summary>
    /// <param name="_N">
    ///     The number of elements to reserve space for.
    /// </param>
    /// <remarks>
    ///     <c>reserve</c> is not concurrency-safe. You must ensure that no other threads are invoking methods
    ///     on the concurrent vector when you call this method. The capacity of the concurrent vector after the method returns
    ///     may be bigger than the requested reservation.
    /// </remarks>
    /**/
    void reserve( size_type _N )
    {
        if( _N )
            _Internal_reserve(_N, sizeof(_Ty), max_size());
    }

    /// <summary>
    ///     Compacts the internal representation of the concurrent vector to reduce fragmentation and optimize memory usage.
    ///     This method is not concurrency-safe.
    /// </summary>
    /// <remarks>
    ///     This method will internally re-allocate memory move elements around, invalidating all the iterators.