System.Console should provide a GetCursorPosition property to get the position atomically

[damageboy]

Currently, the System.Console class in provides two separate properties, CursorLeftand CursorTop that allow the user to change / read the position of the console cursor.

Unfortunately, there seems to be no public API that allows reading the cursor position "atomically" (e.g. both row and column position) although the underlying implementation does get/set the actual position atomically.

Conversly, there does exist a SetCursorPosition public method:
https://github.com/dotnet/corefx/blob/eec001d96a68376c0e504eb7635c8edec196f90f/src/System.Console/src/System/Console.cs#L306

Rational and Usage

The idea would be to be able to read the cursor position on its associated terminal/console in one atomic API call, unlike today, where users of the Console class often write code like:

  var oldX = Console.CursorLeft;
  var oldY = Console.CursotTop;
  Console.SetCursorPosition(0, oldY + 10);
  // Some console output goes out here
  Console.SetCursorPosition(oldX, oldY);

The proposed API would allow reading/setting the position in one API call that would also translate as one atomic system call / write to the underlying OS:

  Console.GetCursorPosition(out var oldX, out var oldY);
  Console.SetCursorPosition(0, oldY + 10);
  // Some console output goes out here
  Console.SetCursorPosition(oldX, oldY);

The proposed change makes reading the console cursor position more readable, efficient (more on that later) and most importantly atomic, in the sense that the API will allow to ensure that the console cursor is/was in the reported position, unlike today, where the console cursor position can change in between calls to the getters/setters of CursorLeft and CursorTop.

Proposed API

namespace System
{
    public static class Console 
    {
        void GetCursorPosition(out int left, out int top);
    }
}

Details

• As mentioned above, the actual implementations already part of CoreFX do support atomic read/write of the cursor position both in Windows / Unix inside the respective ConsolePal classes:
  • Windows:
    https://github.com/dotnet/corefx/blob/ec7a4c6e09d655421195580b7eea887000afc367/src/System.Console/src/System/ConsolePal.Windows.cs#L1078
  • Unix:
    https://github.com/dotnet/corefx/blob/ec7a4c6e09d655421195580b7eea887000afc367/src/System.Console/src/System/ConsolePal.Unix.cs#L348
• The current implementation, esp. in the case of Unix is very heavy and complex, making calling it twice in order to read the complete position is somewhat wasteful, although this is probably a minor consideration in the grand scheme of things.
• For the same reason, In the case of Unix / VT100, implementing atomic reading in user-code (outside CoreFX) is very complex due to the various VT100 quirks that I will not go into here (Reading GetCursorPosition in ConsolePal.Unix.cs linked above makes that abundantly clear).

[danmoseley]

Could you please format like an API proposal (info in docs folder)? That will make API review meeting quicker.

[danmoseley]

@wtgodbe owns this area.

If on at least one platform we can get the value atomically, this seems like a reasonable idea to me.

[danmoseley]

I am not sure the best type as we seem to avoid adding API with tuples (based on a discussion I can't find right now). Point would be nice but it's in winforms.

[stephentoub]

Point would be nice but it's in winforms.

It's in System.Drawing.Primitives in corefx.

[damageboy]

@danmosemsft Will do so (docs).

Currently both ConsolePal.{Unix,Windows}.cs provide an atomic one. The Unix / VT100 one is the super tricky one to nail...

[danmoseley]

@stephentoub thank you, maybe I should not comment on phone where I can't look.

[stephentoub]

😄

[GSPP]

This API should return a struct to not force the caller to accept side-effects with those out parameters. Expressions compose better than statements.

[damageboy]

@GSPP I know what you are talking about, but I thought that it would be slightly weird to have an impedance mismatch between the Set and the Get methods... and since the old API isn't going away...

Do you feel I should re-write this into TWO NEW methods accepting a single struct?

[tannergooding]

This API should return a struct to not force the caller to accept side-effects with those out parameters

What side-effects are you referring to? The overall behavior (and work) for whether you return a struct or two ints is effectively the same.

Returning a struct requires exposing additional public surface area, however.

[damageboy]

@tannergooding I can't find the exact link and therefore the exact name for "this", but I think @GSPP is referring to the fact that out parameters force the JIT to output memory fences/barriers in case the output is a member of a class on the heap.

I also might be completely wrong in my interpretation... :)

[GSPP]

out forces the caller to create variables and to assign to them. That's the side-effect I meant. I am not talking about global state mutation.

Before C# got out var this was much more clunky than it is now. But it still feels impure to me from the perspective of preferring functional code over imperative code. Using functional constructs is a very powerful heuristic for increasing code quality. Expressions are often preferable to statements. Dataflow preferable to side-effects. Pure functions over impure functions. Etc.

For example, out prevents us from treating the result of the function call as any other normal value. We can't pass it around anymore. Essentially, out forces deconstruction.

I also would argue that creating a small struct ConsoleCoordinates is small surface area, very stable over time and easily understood by users.

Maybe this illustrates the point: It is suboptimal API design that int.TryParse returns bool and has an out parameter. This always lead to very clunky code before we got out var. It prevented usage in expression contexts such as LINQ. Better is to return int? (which was not available at the time).

out clearly has it's places but here it seems unnecessary.

Hope these thoughts make sense.

[bartonjs]

Approved with modifications

namespace System
{
    public static class Console 
    {
        public static (int Left, int Top) GetCursorPosition();
    }
}