Documentation for Span<T>

[rpetrusha]

Documentation for Span

• Span Struct Internal Review URL
• Span Enumerator Internal Review URL

Fixes dotnet/docs#4400

• Edited by @JRAlexander - Added internal review links

[pkulikov]

Given that the exception is documented, it's better to say:
Current throws an <xref:System.IndexOutOfRangeException> under any of the following conditions:

Interesting that's the IndexOutOfRangeException rather than InvalidOperationException.

[rpetrusha]

Yes, it is interesting. And you're right, @pkulikov, about replacing the "undefined" text.

[pkulikov]

Is it fine to refer to Span<T> as collection, as in the last sentence? Also given that in the first sentence it's referred as the span.

[rpetrusha]

No, it's not, @pkulikov. Thanks for catching it.

[BillWagner]

Overall, this is a good start.

I had one comment, and you can decide if you think it's a good addition, or unnecessary.

Then, when ready.

[BillWagner]

It may be worth mentioning these two points:

Span<T>.Enumerator does not implement IEnumarator<T>.
Span<T>.Enumerator does not have a Reset() method.

[rpetrusha]

@BillWagner, thanks. These are definitely worth mentioning.

[ahsonkhan]

Looks good to me, in general. Is there a way for me to read the docs in human readable form (without the xml tags)? The links return 404.

Also, do you plan to complete the docs for ReadOnlySpan/Enumerator as well?

[rpetrusha]

I think that the 404s were a result of the published content being deleted, @ahsonkhan. At least, I think that that's what happens when a PR is merged. Sometime tomorrow, the Span docs should be available live on docs.microsoft.com.

@JRAlexander is going to do ReadOnlySpan and ReadOnlySpan.Enumerator.

If you'd like to review the docs once they're live, that would be good. This was a quick-and-dirty attempt to get some documentation online. Sometime next week, I'm planning to enhance the documentation with additional detail and some examples.

[mairaw]

@ahsonkhan given you're an FTE, you can also see the content in the review site: https://review.docs.microsoft.com/en-us/dotnet/api/system.span-1?branch=master&view=netcore-2.1
https://review.docs.microsoft.com/en-us/dotnet/api/system.span-1.enumerator?view=netcore-2.1&branch=master

[ahsonkhan]

cc @KrzysztofCwalina - FYI

[ahsonkhan]

Is using the tilde intentional? T:System.Span~1 In other places we use T:System.Span``1

[mairaw]

Good catch @ahsonkhan. No, they're not by design.

[ahsonkhan]

Should this match the documentation of the GetHashCode method? Both throw NotSupportedException.

[rpetrusha]

I got a compiler error instead, @ahsonkhan. Is that expected?

[ahsonkhan]

private static readonly byte[] _array = new byte[5];
static void Main(string[] args)
{
    Span<byte> span = _array;
    Console.WriteLine(span.Equals(_array));
}

This compiles and builds successfully. At runtime, it throws an exception. I believe that is the expectation:

Unhandled Exception: System.NotSupportedException: Equals() on Span and ReadOnlySpan is not supported. Use operator== instead.
   at System.Span`1.Equals(Object obj)
   at Sample1_Iterating.Program.Main(String[] args) in D:\Other\trash\PipelineTest\Program.cs:line 427

What compiler error are you seeing instead?

[rpetrusha]

Sorry, @ahsonkhan, I missed your question. If obj is not a Span<T>, the exception is thrown. But if obj is a Span<T>, I get compiler error CS1503: cannot convert from 'System.Span' to 'object'

[ahsonkhan]

Ah yes, maybe that's worth mentioning as well. Since span is a ref struct, it cannot be boxed and hence cannot be converted to object. So, the compiler will return such an error if you try to pass in a span to any method that expects an object.

[ahsonkhan]

To guarantee thread safety during enumeration, you can lock the span during the entire enumeration.

@stephentoub, is this true? Couldn't the underlying array still be modified by another thread, or is the implication that the user needs some synchronization mechanism during enumeration and modification of the array? Also, how do we "lock" the span (it isn't a reference type).

The following snippet has a race. To resolve it, we have to use a locking mechanism around both critical sections.
Output:
62
23
0
0
0

static void Main(string[] args)
{
    new Random(42).NextBytes(_array);
    Span<byte> span = _array;

    Thread thread = new Thread(delegate ()
    {
        ClearContents();
    });

    thread.Start();

    EnumerateSpan(span);
}

private static readonly byte[] _array = new byte[5];

public static void ClearContents()
{
    Thread.Sleep(20);
    lock (_array)
    {
        Array.Clear(_array, 0, _array.Length);
    }
}

public static void EnumerateSpan(Span<byte> span)
{
    //lock (_array)
    //{
        foreach (byte element in span)
        {
            Console.WriteLine(element);
            Thread.Sleep(10);
        }
    //}
}

[stephentoub]

First and foremost, there's no way to "lock the span".

Presumably this was really just meant to say that you can use your own synchronization to enforce mutual exclusion.

[ahsonkhan]

At this position, Current throws an exception (it isn't undefined exactly).

[ahsonkhan]

cc'ing others if they have any input to improve the readability/correctness of the span docs that were added here: @dotnet/corefxlab-contrib, @joshfree

[ahsonkhan]

The xml tag around ArraySegment needs an adjustment. It isn't showing up as a link.

[ahsonkhan]

The return type needs to be ref T, not T. Similary, span is a ref struct, not a regular struct.

@rpetrusha, do we generally make a distinction within the docs when a method is marked with an EditorBrowsableState.Never attribute?

@jkotas, should we call out the fact that this method is unsafe within the docs?

[jkotas]

The doc should say that this method is there to support C# fixed statement.

There is nothing unsafe about this method (calling this method directly won't let you violate type or memory safety). I do not think the doc for this method needs to say anything about safety.

We have moved all unsafe Span-related methods to System.Runtime.InteropServices namespace. The documentation for those should mention that they are unsafe.

[BillWagner]

/cc @dend Do you pull the ref from the return type, or make a distinction between struct and ref struct when processing the ref assemblies?

[ahsonkhan]

The API doesn't actually place the original values in a temporary location. It only behaves like this, semantically. The way it is currently written, it conveys the method logic imprecisely.

this method behaves as if the original values are in a temporary location before the destination is overwritten.

[stephentoub]

Most enumerators provide Reset as it's part of the interface but throw or otherwise don't actually implement it.

[stephentoub]

Might be worth mentioning that it's a ref struct and thus can't implement interfaces.

[stephentoub]

Maybe Gets a reference to the item rather than Gets the item?

[stephentoub]

This makes it sound like the memory being represented is type- and memory-safe, rather than it being the representation that is type- and memory-safe.