Improve assert expression documentation. #624

quickfur · 2014-08-01T18:33:16Z

Per discussion on forum.

quickfur · 2014-08-01T18:46:40Z

Web preview: http://eusebeia.dyndns.org/~hsteoh/tmp/web/expression#AssertExpression

DanielGibson · 2014-08-01T18:54:11Z

It's also unclear when AssertError is thrown and when some HALT instruction is executed.
Maybe, while at it, this could also be documented more clearly.
Also remember that assert is documented both in expressions and in the "Contract Programming" section.

quickfur · 2014-08-01T19:42:40Z

AFAIK, assert(0) will always cause the program to halt, no? I'm not sure if distinguishing between HLT and throwing AssertError is that big of an issue, because you aren't supposed to catch Errors anyway. Or if you do, you should only do emergency cleanup and not attempt to recover, because your program is already in an invalid state -- Errors can be thrown from inside nothrow functions, for example, so scope(exit) blocks may not have run, dtors may not have been invoked, etc. Basically, they represent fatal, unrecoverable problems with the program. In practice, if AssertError is thrown, your program is bound to terminate, so I'm not sure it's that much different from HLT. It might be a good idea to give compiler implementors the option to choose between them (on some platforms it might be more practical to just HLT immediately on assertion failure, for example, rather than performing a potentially expensive stack unwinding).

quickfur · 2014-08-01T19:46:55Z

Web preview for contracts page: http://eusebeia.dyndns.org/~hsteoh/tmp/web/contracts

WalterBright · 2014-08-01T20:05:55Z

expression.dd

+
+	$(P It is an error if the $(I expression) contains any side effects
+	that the program depends on. The compiler may optionally not evaluate
+	assert expressions at all.)


Replace with:

$(P It is implementation defined whether the $(I expression) is evaluated at run time or not. Programs that rely on side effects of $(I expression) are invalid.)

tgehr · 2014-08-01T20:31:35Z

The documentation of '-release' and version(assert) need to be updated accordingly as well.

tgehr · 2014-08-01T20:44:06Z

contracts.dd

+	verify that the expression is indeed true.  If it is false, an $(D
+	AssertError) is thrown.)
+
+	$(P When compiling for release, this check is not generated.  The


It is irrelevant to claim it isn't generated. It's undefined behaviour. Undefined behaviour means, it is (maybe unlikely, maybe not what DMD does now, but) theoretically possible that the check is actually generated.

@tgehr If we write it here in the spec, it's no longer undefined.

@Hackerpilot: Undefined behaviour has a precise technical meaning. It overrides anything else you might say about the program, not the other way around. You might be confusing undefined behaviour and unspecified behaviour.

DanielGibson · 2014-08-01T20:53:59Z

Am 01.08.2014 21:42, schrieb H. S. Teoh:

AFAIK, |assert(0)| will /always/ cause the program to halt, no? I'm not
sure if distinguishing between |HLT| and throwing |AssertError| is that
big of an issue, because you aren't supposed to catch Errors anyway.

I'm not talking about the assert(0) special case, but about assert() in
general.
If there was no need to distinguish, AssertError didn't exist.
So I'm sure there is some rule when HLT is executed and when that error
is thrown and it should be documented.

quickfur · 2014-08-01T21:16:03Z

I think Walter's intention is to say that any program that has a failed assertion is invalid by definition, and so its behaviour is undefined. Things like AssertError and HLT are implementation details that the compiler may offer as help for debugging these failed assertions, but one shouldn't be relying on such things being present in the program.

quickfur · 2014-08-01T21:32:54Z

Updated web previews.

quickfur · 2014-08-01T21:38:57Z

@tgehr Where is the documentation for -release? I can't seem to find the page. Do you know the filename?

tgehr · 2014-08-01T21:55:28Z

It is in this and related files linked from there:
http://dlang.org/dmd-linux.html

quickfur · 2014-08-02T00:02:41Z

Update web previews again.

tgehr · 2014-08-02T00:30:20Z

contracts.dd

+	$(I must) uphold. Any failure of this expression represents a logic
+	error in the code that must be fixed.  A program for which the assert
+	contract is false is, by definition, invalid, and therefore has
+	undefined behaviour past that point.)


"past that point" is misleadingly implying that the code before that point won't be affected. If an optimizer can prove that undefined behaviour will occur after some code has executed (in a certain way), it might scrub (transform) that code based on this fact.

tgehr · 2014-08-02T05:57:59Z

There is no treatment of the issue that @safe code will possibly become memory-unsafe if it contains assertions.

ntrel · 2014-08-04T14:27:27Z

expression.dd

+
+	$(P It is implementation defined whether the $(I expression) is
+	evaluated at run time or not. Programs that rely on side effects of $(I
+	expression) are invalid.)


Nitpick: consistently use either the expression or just $(I expression).

quickfur · 2014-08-05T16:52:20Z

@tgehr Where would such treatment be documented, if we were to document it? I'm not sure why we're fixating on asserts in @safe code, because any other language construct that results in undefined behaviour will, by definition, also risk breaking the memory safety of @safe. I believe Walter has stated before that @safe just means it restricts memory-unsafe operations, but it wasn't designed to eliminate undefined behaviour. At least, that's how I understand it.

I think it's really up to Walter how he wants this documented.

tgehr · 2014-08-05T17:10:05Z

http://dlang.org/safed.html
Quote: "SafeD is easy to learn and it keeps the programmers away from undefined behaviors."

quickfur · 2014-08-07T00:51:29Z

I think that page needs to be fixed. Walter & Andrei have repeatedly made it clear that @safe means "no memory corruption", not "no undefined behaviour".

tgehr · 2014-08-07T09:17:26Z

No memory corruption implies no undefined behaviour.

quickfur · 2014-08-07T16:25:58Z

I don't follow. Integer overflow is undefined behaviour, but there is no memory corruption involved.

tgehr · 2014-08-07T18:01:33Z

If the program can behave in any way, it can in particular corrupt memory. (And I am quite confident that given enough time and inclination, one can abuse signed overflow in connection with writing into an array to trick e.g. gdc into emitting a binary that corrupts memory with the appropriate optimization flags even though main is @safe.) In any case, I don't think this is necessarily the right place to discuss this.

ghost · 2014-09-11T09:47:30Z

Can we get an update on this? Looks nice except Walter's and Tgehr's comments.

JakobOvrum · 2014-09-11T09:57:27Z

contracts.dd

-        for more information.)
+	$(P As a contract, an $(D assert) represents a guarantee that the code
+	$(I must) uphold. Any failure of this expression represents a logic
+	error in the code that must be fixed.  A program for which the assert


This could probably benefit from saying "fixed in the source code", so it's perfectly clear that this is not fixable by catching an AssertError.

JakobOvrum · 2014-09-11T10:05:49Z

Asserts are more interesting in @trusted code than @safe code. @safe enforces memory safety without or without asserts, but @trusted doesn't: it's easy to make the mistake of dereferencing a pointer without a runtime safety check just because the same check was done in an assert. In @trusted functions, bounds checking and other related checks must be done with enforce, not assert.

I don't follow. Integer overflow is undefined behaviour, but there is no memory corruption involved.

OT, but integer overflow is defined and expected in D, unlike in C and C++.

Improve assert docs on design-by-contract page too. Improve wording based on comments. Incorporate more suggestions from comments. Reword per comments. Copy-edit. Use less ambiguous wording for version(assert) and -release.

quickfur · 2014-09-11T17:48:29Z

Updated and squashed some commits.

quickfur · 2014-09-20T21:44:19Z

ping

quickfur · 2014-10-02T03:28:49Z

ping @AndrejMitrovic @9rnsr

Improve assert expression documentation.

ghost · 2014-10-02T14:05:50Z

Looks good, thanks for the work!

quickfur · 2014-10-02T17:57:51Z

Thanks!

WalterBright reviewed Aug 1, 2014
View reviewed changes

tgehr reviewed Aug 1, 2014
View reviewed changes

tgehr reviewed Aug 2, 2014
View reviewed changes

ntrel reviewed Aug 4, 2014
View reviewed changes

JakobOvrum reviewed Sep 11, 2014
View reviewed changes

H. S. Teoh added 3 commits September 11, 2014 10:45

Improve assert expression documentation.

f46cd3f

Improve assert docs on design-by-contract page too. Improve wording based on comments. Incorporate more suggestions from comments. Reword per comments. Copy-edit. Use less ambiguous wording for version(assert) and -release.

Update based on comments.

bede769

Update assert docs according to reviewer comments.

279d262

quickfur force-pushed the assert_doc branch 2 times, most recently from 0b385cf to 279d262 Compare September 11, 2014 17:47

ghost pushed a commit that referenced this pull request Oct 2, 2014

Merge pull request #624 from quickfur/assert_doc

cd99fd8

Improve assert expression documentation.

ghost merged commit cd99fd8 into dlang:master Oct 2, 2014

quickfur deleted the assert_doc branch October 2, 2014 17:58

This pull request was closed.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve assert expression documentation. #624

Improve assert expression documentation. #624

quickfur commented Aug 1, 2014

quickfur commented Aug 1, 2014

DanielGibson commented Aug 1, 2014

quickfur commented Aug 1, 2014

quickfur commented Aug 1, 2014

WalterBright Aug 1, 2014

tgehr commented Aug 1, 2014

tgehr Aug 1, 2014

Hackerpilot Aug 1, 2014

tgehr Aug 1, 2014

DanielGibson commented Aug 1, 2014

quickfur commented Aug 1, 2014

quickfur commented Aug 1, 2014

quickfur commented Aug 1, 2014

tgehr commented Aug 1, 2014

quickfur commented Aug 2, 2014

tgehr Aug 2, 2014

tgehr commented Aug 2, 2014

ntrel Aug 4, 2014

quickfur commented Aug 5, 2014

tgehr commented Aug 5, 2014

quickfur commented Aug 7, 2014

tgehr commented Aug 7, 2014

quickfur commented Aug 7, 2014

tgehr commented Aug 7, 2014

ghost commented Sep 11, 2014

JakobOvrum Sep 11, 2014

JakobOvrum commented Sep 11, 2014

quickfur commented Sep 11, 2014

quickfur commented Sep 20, 2014

quickfur commented Oct 2, 2014

ghost commented Oct 2, 2014

quickfur commented Oct 2, 2014

Improve assert expression documentation. #624

Improve assert expression documentation. #624

Conversation

quickfur commented Aug 1, 2014

quickfur commented Aug 1, 2014

DanielGibson commented Aug 1, 2014

quickfur commented Aug 1, 2014

quickfur commented Aug 1, 2014

WalterBright Aug 1, 2014

Choose a reason for hiding this comment

tgehr commented Aug 1, 2014

tgehr Aug 1, 2014

Choose a reason for hiding this comment

Hackerpilot Aug 1, 2014

Choose a reason for hiding this comment

tgehr Aug 1, 2014

Choose a reason for hiding this comment

DanielGibson commented Aug 1, 2014

quickfur commented Aug 1, 2014

quickfur commented Aug 1, 2014

quickfur commented Aug 1, 2014

tgehr commented Aug 1, 2014

quickfur commented Aug 2, 2014

tgehr Aug 2, 2014

Choose a reason for hiding this comment

tgehr commented Aug 2, 2014

ntrel Aug 4, 2014

Choose a reason for hiding this comment

quickfur commented Aug 5, 2014

tgehr commented Aug 5, 2014

quickfur commented Aug 7, 2014

tgehr commented Aug 7, 2014

quickfur commented Aug 7, 2014

tgehr commented Aug 7, 2014

ghost commented Sep 11, 2014

JakobOvrum Sep 11, 2014

Choose a reason for hiding this comment

JakobOvrum commented Sep 11, 2014

quickfur commented Sep 11, 2014

quickfur commented Sep 20, 2014

quickfur commented Oct 2, 2014

ghost commented Oct 2, 2014

quickfur commented Oct 2, 2014