|
From: Nicholas N. <nj...@cs...> - 2005-02-25 20:04:09
Attachments:
valgrind-quick-start
|
Hi, I just, for the first time, found myself in the situation of introducing Valgrind to multiple people. And so I realised that we are sorely lacking a "Quick Start Guide", which tells people the minimum amount of information required to start using Memcheck. And so I wrote one. It's attached. Feedback is welcome. I think this would be useful to make official, either as part of the user manual, or maybe as a separate doc. I can HTML it and commit it if people think this is a good idea. As a result of writing this, I think we should do the following: - make --leak-check=yes the default for Memcheck - increase the default --num-callers size to 12 Why? Partly because in the quick start I immediately suggest starting with this command line: valgrind --tool=memcheck --num-callers=40 --leak-check=yes ... because that's what I think is most useful. And I think that's most useful because the survey responses I've received in the last year (14 of them) almost everyone uses --leak-check=yes all the time, and most people immediately crank up --num-callers to at least 10 (and sometimes much higher, eg. 40). --show-reachable=yes is also pretty popular, but I don't think it's quite popular enough to make the default. So, the quick start would then be shorter, since I wouldn't have to explain those options. I think it's currently already too long, but it's only a draft. I think this document and these settings changes would lower the bar for new users to get Memcheck working usefully as quickly as possible, which is what 95% of users would want, and is something we should aim for. Comments? N |
|
From: Jeremy F. <je...@go...> - 2005-02-25 21:49:05
|
Nicholas Nethercote wrote:
> - make --leak-check=yes the default for Memcheck
Maybe. For simply running a program its a good default, but running a
shell script (with lots of exits) can be hit quite hard by --leak-check
(though its a bit more efficient now). Also, if a program is using
DO_LEAK_CHECK, they might not want an implicit one too.
> - increase the default --num-callers size to 12
Yes! I was about to propose this. 4 has been way too small for a long
time. Also, the default --leak-resolution=low (2 frames matches) is too
low as well; I think it should default to "med".
And should we consider defaulting to memcheck again?
> And I think that's most useful because the survey responses I've
> received in the last year (14 of them) almost everyone uses
> --leak-check=yes all the time, and most people immediately crank up
> --num-callers to at least 10 (and sometimes much higher, eg. 40).
> --show-reachable=yes is also pretty popular, but I don't think it's
> quite popular enough to make the default.
I find --show-reachable is too noisy for common use.
> So, the quick start would then be shorter, since I wouldn't have to
> explain those options. I think it's currently already too long, but
> it's only a draft.
>
> I think this document and these settings changes would lower the bar
> for new users to get Memcheck working usefully as quickly as possible,
> which is what 95% of users would want, and is something we should aim
> for.
>
> Comments?
>
> N
>
>------------------------------------------------------------------------
>
>Valgrind quick start
>--------------------
>This document contains the minimum information you should know to start
>detecting memory errors in your program with Valgrind.
>
>The Valgrind distribution has multiple tools. The memory checking tool
>(called Memcheck) can detect many common memory errors such as:
>
>- touching memory you shouldn't (eg. overrunning heap block boundaries)
>- using values before they have been initialized
>- incorrect freeing of memory, such as double-freeing heap blocks
>- memory leaks
>
>Here's how to use it.
>
>1. Preparing your program. Compile your program with debugging information so
>that Memcheck's error messages include exact line numbers.
>
>
I'd add "(-g)" after "debugging information", just to be explicit.
>2. Running your program under Memcheck. If you normally run your program
>like this:
>
> myprog arg1 arg2 arg3
>
>Use this command line:
>
> valgrind --tool=memcheck --num-callers=40 --leak-check=yes myprog arg2 arg2 arg3
>
>The --tool option invokes Memcheck. The --num-callers option asks for big
>stack traces, which make error messages more informative. The --leak-check
>option turns on the memory leak detector.
>
>Your program will run much slower (eg. 20 to 30 times) than normal.
>Memcheck will describe any errors it detects. When your program terminates,
>Memcheck will describe any memory leaks it detects.
>
>3. Interpreting Memcheck's output. Here's an example C program with two
>memory errors.
>
> #include <stdio.h>
> #include <stdlib.h>
>
> int f(void)
> {
> int* x = malloc(10 * sizeof(int));
> x[10] = 0; // problem 1: heap block overrun
> return; // problem 2: memory leak -- x not freed
> }
>
> int main(void)
> {
> f();
> return 0;
> }
>
>Most error messages look like the following, which describes problem 1, the
>heap block overrun:
>
> ==19182== Invalid write of size 4
> ==19182== at 0x804838F: f (a.c:8)
> ==19182== by 0x80483AB: main (a.c:14)
> ==19182== Address 0x1BA45050 is 0 bytes after a block of size 40 alloc'd
> ==19182== at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130)
> ==19182== by 0x8048385: f (a.c:7)
> ==19182== by 0x80483AB: main (a.c:14)
>
>Things to notice:
>- There is a lot of information in each error message; read it carefully.
>
>- The 19182 is the process ID; it's usually unimportant.
>
>- The first line ("Invalid write...") tells you what the error is. Here,
> the program wrote to some memory it should not have due to a heap block
> overrun.
>
>- Below the first line is a stack trace. Stack traces can get quite large,
> and be confusing, especially if you are using the C++ STL. Reading them
> from the bottom up can help. If the stack trace is not big enough, use a
> bigger --num-callers option.
>
>- The addresses (eg. 0x804838F) are usually unimportant, but occasionally
> crucial for tracking down weirder bugs.
>
>- Some error messages, such as this one, have a second component which
> describes the memory address involved, and possibly give another stack
> trace showing where it was allocated or freed.
>
>
I would explicitly, but briefly, describe the Address block.
Looks good.
J
|
|
From: Julian S. <js...@ac...> - 2005-02-25 23:45:34
|
Nice summary. Definitely a good thing. > > - increase the default --num-callers size to 12 > > Yes! I was about to propose this. 4 has been way too small for a long > time. Also, the default --leak-resolution=low (2 frames matches) is too > low as well; I think it should default to "med". Yes, perhaps time to increase --num-callers. Problem with large values is that error messages take up tons of screen space. Oh well. Default 8 ? 12 ? > And should we consider defaulting to memcheck again? Personally I would like that. I find it annoying to constantly have to type --tool=memcheck (but not _always_, so .valgrindrc isn't the answer). Indeed, I am not the only one: the V that comes packaged with SuSE seems to already have been defaulted to memcheck, presumably by the SuSE folks themselves. (iow, "valgrind ls" works fine on SuSE). > I find --show-reachable is too noisy for common use. I agree. I hesitate to run the leak checker by default at exit. It can cause a huge amount of disk activity because it inspects bits of address space that had been swapped out during long runs of leaky programs, and which then gets forced back in as the checker traverses it all. But perhaps we should. In an underhand way it creates the expectation amongst programmers that their programs should have no detectable leaks, and that leaks will be tested for routinely -- every time V is run. And it helps our software engineering too. Currently the checker is basically an optional component and doesn't get tested enough. If it was engaged by default, we would know much sooner if there was anything broken about it. J |
|
From: Jeremy F. <je...@go...> - 2005-02-26 00:11:53
|
Julian Seward wrote:
> I hesitate to run the leak checker by default at exit. It can
> cause a huge amount of disk activity because it inspects bits of
> address space that had been swapped out during long runs of
> leaky programs, and which then gets forced back in as the checker
> traverses it all.
>
> But perhaps we should. In an underhand way it creates the
> expectation amongst programmers that their programs should have
> no detectable leaks, and that leaks will be tested for routinely
> -- every time V is run.
Well, since it's mark-sweep now, a basic leak check only traverses the
live heap. We could report the total number of leaked blocks/memory
pretty quickly. Its only doing a decent job of reporting specific leaks
which requires walking the leaked part of the heap.
Also, the checker touches a lot less memory than it used to; it doesn't
bother scanning read-only memory, for example (since it can never
contain pointers to the heap).
J
|
|
From: Nicholas N. <nj...@cs...> - 2005-02-25 21:54:09
|
On Fri, 25 Feb 2005, Jeremy Fitzhardinge wrote: >> - make --leak-check=yes the default for Memcheck > > Maybe. For simply running a program its a good default, but running a > shell script (with lots of exits) can be hit quite hard by --leak-check > (though its a bit more efficient now). Also, if a program is using > DO_LEAK_CHECK, they might not want an implicit one too. I argue that scripts and programs using DO_LEAK_CHECK are in the minority. > And should we consider defaulting to memcheck again? I don't think so; it is still the best way to imply that there are other tools. N |
|
From: Robert W. <rj...@du...> - 2005-02-25 22:40:52
|
> > And should we consider defaulting to memcheck again? >=20 > I don't think so; it is still the best way to imply that there are other= =20 > tools. I vote for a default too. I use memcheck 95% of the time and it's getting tiring typing those extra letters :-) --=20 Robert Walsh Amalgamated Durables, Inc. - "We don't make the things you buy." Email: rj...@du... |
|
From: Nicholas N. <nj...@cs...> - 2005-02-25 22:46:46
|
On Fri, 25 Feb 2005, Robert Walsh wrote: >>> And should we consider defaulting to memcheck again? >> >> I don't think so; it is still the best way to imply that there are other >> tools. > > I vote for a default too. I use memcheck 95% of the time and it's > getting tiring typing those extra letters :-) That's what the .valgrindrc file is for :) N |
|
From: Nicholas N. <nj...@cs...> - 2005-02-27 19:59:14
|
On Fri, 25 Feb 2005, Julian Seward wrote: >> And should we consider defaulting to memcheck again? > > Personally I would like that. I find it annoying to constantly > have to type --tool=memcheck (but not _always_, so .valgrindrc > isn't the answer). .valgrindrc works with that. I'm in the same situation, so I have --tool=memcheck in my .valgrindrc, and if I want to run something else I just put that on the command line; command line-specified options take precedence over the .valgrindrc ones so it all just works. I'm not convinced about defaulting to Memcheck, but if I'm overruled, so be it. Recall that I originally made this change in response to the survey responses from November 2003 -- many people were confused about this, and didn't realise that Valgrind != Memcheck. I think we still have that confusion, although perhaps it's not so bad now that we use "tool" consistently rather than "skin". If we do default to Memcheck, I could mention the existence of other tools briefly in the Quick Start guide, maybe that would be enough. > But perhaps we should. In an underhand way it creates the > expectation amongst programmers that their programs should have > no detectable leaks, and that leaks will be tested for routinely > -- every time V is run. Yes, so that's good. > And it helps our software engineering too. Currently the checker > is basically an optional component and doesn't get tested enough. > If it was engaged by default, we would know much sooner if there was > anything broken about it. I think it gets used plenty by real people, but we as developers don't test it much. But it's still a good point. We'd have to change the test outputs a lot, though. ---- FWIW, I analysed the 14 newer survey responses more carefully. Here are the counts for the always/almost always used options, and the sometimes used options: Always/almost always used: --leak-check: 10 --num-callers: 7 (10 or more, 16, 10, 100, 8, 10, 10) --tool=memcheck: 4 (under-reported) --show-reachable: 4 --suppressions: 2 --trace-children=yes: 2 --error-limit=no: 1 -q: 1 Sometimes used: --leak-check: 5 --show-reachable: 3 --gdb-attach: 2 --logfile-fd=4 2 (4, -1) --leak-resolution=high: 2 --num-callers: 2 (30, 8) -v: 1 --help: 1 [I see that the --leak-check counts add up to 15. Must have counted one twice, whoops.] I guess the aim here should be that there is no option that a majority of users are almost always setting -- anything like that should be a default. Analysis and recommendations: * 12/14 use Memcheck 90% or more of the time. (The count of 4 is under-reported.) Recommendation: make it default again, and make it clear in the quick start guide that there are other tools. * Approx 2/3 of respondents used --leak-check always/almost always, the rest sometimes use it. Recommendation: make --leak-check=yes the default. * Half of users always increase --num-callers, and 2/14 sometimes do. It looks like 10 might be a good default, maybe 12. I'm guessing those that put it much higher are using C++ STL. (You could argue that it should be much higher, since it's probably not such a bad thing to have the whole trace present.) Recommendation: make --num-callers=12 the default. * --show-reachable=yes is quite popular, but not super-popular. Recommendation: leave --show-reachable=no the default. If no-one objects, I will commit these changes soon. N |
|
From: Rich C. <Ric...@me...> - 2005-03-09 22:10:09
|
On Sun, 27 Feb 2005 13:59:10 -0600 (CST) Nicholas Nethercote <nj...@cs...> wrote: > On Fri, 25 Feb 2005, Julian Seward wrote: > > >> And should we consider defaulting to memcheck again? > > > > Personally I would like that. I find it annoying to constantly > > have to type --tool=memcheck (but not _always_, so .valgrindrc > > isn't the answer). > > .valgrindrc works with that. I'm in the same situation, so I have > --tool=memcheck in my .valgrindrc, and if I want to run something else I > just put that on the command line; command line-specified options take > precedence over the .valgrindrc ones so it all just works. > .valgrindrc works great when you are running code as your self on your own box. When you are working on a target in a production type environment, there is no .valgrindrc. I'd vote for the default of --tool=memcheck. -- Rich Coe ric...@me... General Electric Healthcare Technologies Global Software Platfroms, Computer Technology Team |
|
From: Jeremy F. <je...@go...> - 2005-02-28 00:57:07
|
Nicholas Nethercote wrote:
> * Approx 2/3 of respondents used --leak-check always/almost always, the
> rest sometimes use it.
>
> Recommendation: make --leak-check=yes the default.
What about a lightweight leak-check which is always enabled, but only
reports a summary of leaked memory, and a CLO which reports the full
details of leaked memory?
J
|
|
From: Nicholas N. <nj...@cs...> - 2005-02-28 14:41:02
|
On Sun, 27 Feb 2005, Jeremy Fitzhardinge wrote: >> Recommendation: make --leak-check=yes the default. > > What about a lightweight leak-check which is always enabled, but only > reports a summary of leaked memory, and a CLO which reports the full > details of leaked memory? I don't see much point. People are mostly using --leak-check=yes, let's give them what they're (indirectly) asking for. N |
|
From: Julian S. <js...@ac...> - 2005-02-28 14:57:26
|
> >> Recommendation: make --leak-check=yes the default. > > > > What about a lightweight leak-check which is always enabled, but only > > reports a summary of leaked memory, and a CLO which reports the full > > details of leaked memory? > > I don't see much point. People are mostly using --leak-check=yes, let's > give them what they're (indirectly) asking for. I vote for permanently-enabled summary only, with --leak-check=yes doing the full thing. Advantages: * it continually reminds users that leak checking is available * having the full output enabled by default floods people with too much info they may not want * it means the leak checker is continually exercised, exposing any bugs sooner J |
|
From: Nicholas N. <nj...@cs...> - 2005-03-01 00:34:00
|
On Mon, 28 Feb 2005, Julian Seward wrote: >>>> Recommendation: make --leak-check=yes the default. >>> >>> What about a lightweight leak-check which is always enabled, but only >>> reports a summary of leaked memory, and a CLO which reports the full >>> details of leaked memory? >> >> I don't see much point. People are mostly using --leak-check=yes, let's >> give them what they're (indirectly) asking for. > > I vote for permanently-enabled summary only, with --leak-check=yes > doing the full thing. Would you be able to turn the leak checker off? I think you should still be able to do that. It takes time, if someone doesn't want to use it, they shouldn't have to. > Advantages: > > * it continually reminds users that leak checking is available > > * it means the leak checker is continually exercised, exposing > any bugs sooner These two are true if you have the full output showing too. > * having the full output enabled by default floods people with too > much info they may not want I disagree. I think it's like increasing num-callers -- there's a reasonable concern with flooding the user with too much info, but really the surveys have clearly shown that's what they want. It's better to have too much info than not enough and have to run your program again. Having said that, you're the boss. N |
|
From: Julian S. <js...@ac...> - 2005-03-01 20:48:13
|
> > I vote for permanently-enabled summary only, with --leak-check=yes > > doing the full thing. > > Would you be able to turn the leak checker off? Err, I hadn't thought of that. Ok. I change my vote. Let's have --leak-check=yes|summary|no, with the default being yes, and summary ... well, just producing a summary. When =yes is in effect, we should also print a line saying "use ...=summary or ...=no to reduce the amount of output." J |