Add todo!() macro

[matklad]

The primary use-case of todo!() macro is to be a much easier to type
alternative to unimplemented!() macro.

EDIT: hide unpopular proposal about re-purposing unimplemented

However, instead of just replacing `unimplemented!()`, it gives it a more nuanced meaning: a thing which is intentionally left unimplemented and which should not be called at runtime. Usually, you'd like to prevent such cases statically, but sometimes you, for example, have to implement a trait only some methods of which are applicable. There are examples in the wild of code doing this thing, and in this case, the current message of `unimplemented`, "not *yet* implemented" is slightly misleading.

With the addition of TODO, you have three nuanced choices for a
!-returning macro (in addition to a good-old panic we all love):

• todo!()
• unreachable!()
• unimplemented!()

Here's a rough guideline what each one means:

• todo: use it during development, as a "hole" or placeholder. It
  might be a good idea to add a pre-commit hook which checks that
  todo is not accidentally committed.

• unreachable!(): use it when your code can statically guarantee
  that some situation can not happen. If you use a library and hit
  unreachable!() in the library's code, it's definitely a bug in the
  library. It's OK to have unreachable!() in the code base,
  although, if possible, it's better to replace it with
  compiler-verified exhaustive checks.

• unimplemented!(): use it when the type checker forces you to
  handle some situation, but there's a contract that a callee must not
  actually call the code. If you use a library and hit
  unimplemented!(), it's probably a bug in your code, though
  it could be a bug in the library (or library docs) as well. It is
  ok-ish to see an unimplemented!() in real code, but it usually
  signifies a clunky, eyebrow-rising API.

[rust-highfive]

r? @dtolnay

(rust_highfive has picked a reviewer for you, use r? to override)

[matklad]

internals discussion: https://internals.rust-lang.org/t/micro-pre-rfc-todo-macro/8925

[matklad]

Example where unimplemented means: "no reasonable implementation exists" as opposed to "will write an impl really soon":

rust/src/bootstrap/builder.rs

Lines 89 to 95 in 3dde9e1

	fn make_run(_run: RunConfig) {
	// It is reasonable to not have an implementation of make_run for rules
	// who do not want to get called from the root context. This means that
	// they are likely dependencies (e.g., sysroot creation) or similar, and
	// as such calling them from ./x.py isn't logical.
	unimplemented!()
	}

[cuviper]

I like that this distinguishes intent -- todo!() means you'll get around to it later, whereas unimplemented!() means you'll leave it that way. To that end, the documentation for the latter should also be updated, and probably remove the "yet" from its panic message. Maybe also audit rustc's own uses to see which ones might better be todo!().

[rust-highfive]

The job x86_64-gnu-llvm-5.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

travis_time:end:27772262:start=1543519340157852467,finish=1543519341278502081,duration=1120649614
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#Pull-Requests-and-Security-Restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-5.0
---
[00:03:08] tidy error: /checkout/src/libcore/macros.rs:581: trailing whitespace
[00:03:10] some tidy checks failed
[00:03:10] 
[00:03:10] 
[00:03:10] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/tidy" "/checkout/src" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "--no-vendor" "--quiet"
[00:03:10] 
[00:03:10] 
[00:03:10] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:03:10] Build completed unsuccessfully in 0:00:55
[00:03:10] Build completed unsuccessfully in 0:00:55
[00:03:10] Makefile:79: recipe for target 'tidy' failed
[00:03:10] make: *** [tidy] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:15d2ea0c
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Thu Nov 29 19:25:40 UTC 2018
---
travis_time:end:15dae23c:start=1543519540672929511,finish=1543519540676677389,duration=3747878
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:0668e7c2
$ ln -s . checkout && for CORE in obj/cores/core.*; do EXE=$(echo $CORE | sed 's|obj/cores/core\.[0-9]*\.!checkout!\(.*\)|\1|;y|!|/|'); if [ -f "$EXE" ]; then printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" "$CORE"; gdb --batch -q -c "$CORE" "$EXE" -iex 'set auto-load off' -iex 'dir src/' -iex 'set sysroot .' -ex bt -ex q; echo travis_fold":"end:crashlog; fi; done || true
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:00967fbc
travis_time:start:00967fbc
$ cat ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
cat: ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers: No such file or directory
travis_fold:end:after_failure.5
travis_fold:start:after_failure.6
travis_time:start:078dae70
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

[matklad]

To that end, the documentation for the latter should also be updated, and probably remove the "yet" from its panic message.

Oups, was meant to add that to commit message. That obviously should be done, but only when/if we stabilize the todo! macro.

[kennytm]

I wonder if we should name it TODO!() so it could match the // TODO comments.

Prior arts for breaking the naming convention: Go, Kotlin

[Centril]

The unimplemented macro also has this sentence in the docs so you probably want to re-frame that documentation.

[matklad]

We can do that only when we stabilize todo: #56348 (comment)

[steveklabnik]

aren't macros insta-stable?

[cuviper]

There are other unstable macros already, like concat_idents!

[yoshuawuyts]

@steveklabnik I believe not necessarily. The dbg!() macro went through nightly first, and is only now landing on stable.

[scottmcm]

I think relegating panic! to a parenthetical is being misleading. I don't think "there's a contract that a callee must not actually call the code" is unimplemented!(), I think it's a place for a panic! (or assert!) with a message actually explaining this fact. And then there's no need for another name for the same thing.

Prior art:

• https://docs.microsoft.com/en-us/dotnet/api/system.notimplementedexception
• https://docs.microsoft.com/en-us/dotnet/api/system.notsupportedexception

[matklad]

@scottmcm not sure I entirely understand what you are trying to say, so let me to elaborate on my goals here:

The single reason is that I want to shorten unimplemented to todo. Ideally, I wish it was named todo from the start.

However, we already have unimplemented, so we need to do something about it.

One choice is to deprecate, another choice is to repurpose. The PR description went with repurposing, because, after grepping rust-lang/rust, I’ve noticed that it already is being used in the C#’s not supported sense.

[joshtriplett]

I'm entirely in favor of this.

[bors]

☔️ The latest upstream changes (presumably #56275) made this pull request unmergeable. Please resolve the merge conflicts.

[Thomasdezeeuw]

Shouldn't this say "panics"?

[Thomasdezeeuw]

This says to use the unimplemented macro.

[matklad]

Renamed to TODO!

[Centril]

I'm not sure TODO! is better... there's no precedent for that in Rust and it seems harder to type in general?

[rust-highfive]

The job x86_64-gnu-llvm-5.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

travis_time:end:284da6b6:start=1543998742241291062,finish=1543998743276341899,duration=1035050837
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#Pull-Requests-and-Security-Restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-5.0
---

[00:03:05] travis_fold:start:tidy
travis_time:start:tidy
tidy check
[00:03:05] tidy error: /checkout/src/libcore/macros.rs:578: TODO is deprecated; use FIXME
[00:03:05] tidy error: /checkout/src/libcore/macros.rs:596: TODO is deprecated; use FIXME
[00:03:05] tidy error: /checkout/src/libcore/macros.rs:609: TODO is deprecated; use FIXME
[00:03:06] tidy error: /checkout/src/libstd/lib.rs:337: TODO is deprecated; use FIXME
[00:03:07] some tidy checks failed
[00:03:07] 
[00:03:07] 
[00:03:07] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/tidy" "/checkout/src" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "--no-vendor" "--quiet"
[00:03:07] 
[00:03:07] 
[00:03:07] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:03:07] Build completed unsuccessfully in 0:00:56
[00:03:07] Build completed unsuccessfully in 0:00:56
[00:03:07] Makefile:79: recipe for target 'tidy' failed
[00:03:07] make: *** [tidy] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:18cd5548
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Wed Dec  5 08:35:39 UTC 2018
---
travis_time:end:1aa5cc19:start=1543998939736380146,finish=1543998939740980375,duration=4600229
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:05ae06dc
$ ln -s . checkout && for CORE in obj/cores/core.*; do EXE=$(echo $CORE | sed 's|obj/cores/core\.[0-9]*\.!checkout!\(.*\)|\1|;y|!|/|'); if [ -f "$EXE" ]; then printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" "$CORE"; gdb --batch -q -c "$CORE" "$EXE" -iex 'set auto-load off' -iex 'dir src/' -iex 'set sysroot .' -ex bt -ex q; echo travis_fold":"end:crashlog; fi; done || true
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:0a429d14
travis_time:start:0a429d14
$ cat ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
cat: ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers: No such file or directory
travis_fold:end:after_failure.5
travis_fold:start:after_failure.6
travis_time:start:1c73da86
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

[Ralith]

An all-caps macro strikes me as a large enough digression from Rust style conventions to be immediately confusing to a reader.

[matklad]

Don't have an opinion about which capitalization is better, will leave that to libs team to decide. Both Kotlin & Go decided to change naming convention for this macro though.

[mark-i-m]

There is some precedent: TODO in comments tends to be all caps.

[Ralith]

TODO in comments is not a macro invocation.

[mark-i-m]

I know, but it is related to TODOs...

[bors]

☔️ The latest upstream changes (presumably #56066) made this pull request unmergeable. Please resolve the merge conflicts.

[dtolnay]

I am sympathetic to unimplemented!() being complicated to type. At this point I have muscle memory for it but it took a while.

At the same time I agree with @scottmcm in #56348 (comment) and would prefer not to see unimplemented!() become what you wrote in the PR description: "there's a contract that a callee must not actually call the code." That would be panic or assert. The panic or assert message should explain the contract. The point is that the caller broke the contract, not that the code isn't implemented.

I am pretty ambivalent but probably leaning against making this change -- meaning I would continue to use unimplemented!() over todo!() if both were available and meant the same thing. I'll reassign to Boats because I am interested in your take and I see your 👍.

Regarding capitalization, I would advise against weighing Go as precedent. They were hamstrung by requiring a capital first letter on public functions, at which point ToDo is just distracting and Todo is Spanish. In Rust I would want the name to be in lowercase.

r? @withoutboats

[matklad]

rebased and created&filled the tracking issue

[withoutboats]

@matklad This looks good and I'd like to request just one more change: add a sentence to the docs of both todo and unimplemented documenting that each has the same behavior as the other, so no one wastes time scrutinizing them looking for a difference.

[matklad]

I think we should only change unimplemented docs when/if we actually stabilize todo!. Added the note to todo

[withoutboats]

that makes sense to me

@bors r+

[bors]

📌 Commit c11b37a has been approved by withoutboats

[rust-highfive]

The job x86_64-gnu-llvm-6.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

travis_time:end:14e04bbf:start=1552925416202863259,finish=1552925417399815597,duration=1196952338
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
$ export GCP_CACHE_BUCKET=rust-lang-ci-cache
Setting environment variables from .travis.yml
---
[00:04:40] tidy error: /checkout/src/libcore/macros.rs:565: trailing whitespace
[00:04:42] some tidy checks failed
[00:04:42] 
[00:04:42] 
[00:04:42] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/tidy" "/checkout/src" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "--no-vendor" "--quiet"
[00:04:42] 
[00:04:42] 
[00:04:42] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:04:42] Build completed unsuccessfully in 0:00:48
[00:04:42] Build completed unsuccessfully in 0:00:48
[00:04:42] make: *** [tidy] Error 1
[00:04:42] Makefile:67: recipe for target 'tidy' failed
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:1e13e730
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Mon Mar 18 16:15:10 UTC 2019
---
travis_time:end:10f654ac:start=1552925711948310320,finish=1552925711953568162,duration=5257842
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:068dd111
$ ln -s . checkout && for CORE in obj/cores/core.*; do EXE=$(echo $CORE | sed 's|obj/cores/core\.[0-9]*\.!checkout!\(.*\)|\1|;y|!|/|'); if [ -f "$EXE" ]; then printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" "$CORE"; gdb --batch -q -c "$CORE" "$EXE" -iex 'set auto-load off' -iex 'dir src/' -iex 'set sysroot .' -ex bt -ex q; echo travis_fold":"end:crashlog; fi; done || true
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:22a15fe6
travis_time:start:22a15fe6
$ cat ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
cat: ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers: No such file or directory
travis_fold:end:after_failure.5
travis_fold:start:after_failure.6
travis_time:start:175b65a0
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

[withoutboats]

@bors r+

[bors]

📌 Commit 9d408d9 has been approved by withoutboats

[Centril]

@bors rollup

[jonhoo]

Just going to leave a link to #39930 and rust-lang/rfcs#1911 here so that we maintain the breadcrumbs for people digging later on.

[mikhail-krainik]

I cannot understand why people think that “todo” is “panic”. Historically //TODO is a note that does not violate your program. But this discussion said todo! have to break your program.

#[macro_export]
#[unstable(feature = "todo_macro", issue = "59277")]
macro_rules! todo {
    () => (panic!("not yet implemented"));
    ($($arg:tt)+) => (panic!("not yet implemented: {}", format_args!($($arg)*)));
}

We have a lot of important RFC. Let's leave the unimplemented!() alone.

[CAD97]

The convention that this is making easier is not unprecedented.

A lot of development flows say that // TODO should not be committed, and should be a local development marker; the committed version is // FIXME.

In addition, this makes no change to // TODO, and you can continue using it per whatever convention you want.

The purpose of this is more to provide todo!() as an alternative to unimplemented!() such that you can have a similar convention as is used between // TODO and // FIXME. (The proposed distinction is that todo!() is for short lived and unimplemented!() is for longer lived, but this does not require that of you.)

[mikhail-krainik]

The convention that this is making easier is not unprecedented.

easy shouldn't be confusing

A lot of development flows say that // TODO should not be committed, and should be a local development marker; the committed version is // FIXME.

A lot of people say that earth is flat. But https://en.wikipedia.org/wiki/Comment_(computer_programming) says "TODO – something to be done."

In addition, this makes no change to // TODO, and you can continue using it per whatever convention you want.

todo! mustn't raise an error.

The purpose of this is more to provide todo!() as an alternative to unimplemented!() such that you can have a similar convention as is used between // TODO and // FIXME. (The proposed distinction is that todo!() is for short lived and unimpleunimplementedmented!() is for longer lived, but this does not require that of you.)

If you want to see a shorter version than unimplemented!() without losing clarity, I offer unimpl!() or just keep unimplemented!()