From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 19865 invoked by alias); 4 Oct 2013 10:07:48 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 19818 invoked by uid 89); 4 Oct 2013 10:07:48 -0000 Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Fri, 04 Oct 2013 10:07:48 +0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.3 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: mx1.redhat.com Received: from int-mx01.intmail.prod.int.phx2.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id r94A7hLR029960 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 4 Oct 2013 06:07:44 -0400 Received: from [127.0.0.1] (ovpn01.gateway.prod.ext.ams2.redhat.com [10.39.146.11]) by int-mx01.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id r94A7f9M008699; Fri, 4 Oct 2013 06:07:42 -0400 Message-ID: <524E936D.9040401@redhat.com> Date: Fri, 04 Oct 2013 10:07:00 -0000 From: Pedro Alves User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130625 Thunderbird/17.0.7 MIME-Version: 1.0 To: Tom Tromey CC: gdb-patches@sourceware.org, Joel Brobecker Subject: Re: [PATCH] Clean up ptid.h/ptid.c. References: <1380809351-20800-1-git-send-email-palves@redhat.com> <87ioxez3ct.fsf@fleche.redhat.com> In-Reply-To: <87ioxez3ct.fsf@fleche.redhat.com> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-SW-Source: 2013-10/txt/msg00138.txt.bz2 On 10/04/2013 08:30 AM, Joel Brobecker wrote: > I like it! Thanks for doing this cleanup, Pedro. Great! You're welcome. On 10/03/2013 06:11 PM, Tom Tromey wrote: > Looks good to me. > It's my preferred approach. > I usually write /* See ptid.h. */ in these spots. Thanks, added and checked in, as below. ----- Clean up ptid.h/ptid.c. The ptid_t contructors, accessors and predicates are documented in _three_ places, and each place uses a different wording. E.g, the descriptions in the .c file of the new ptid_lwp_p, ptid_tid_p weren't updated in the final revision like the descriptions in the .h file were. Clearly, switching to a style that has a single central description avoids such issues. Worse, some of the existing descriptions are plain wrong, such as: /* Attempt to find and return an existing ptid with the given PID, LWP, and TID components. If none exists, create a new one and return that. */ ptid_t ptid_build (int pid, long lwp, long tid); The function does nothing that complicated. It's just a simple constructor. So this gets rid of all the unnecessary descriptions, leaving only the ones near the function declarations in the header file, and fixes/clarifies those that remain. gdb/ 2013-10-04 Pedro Alves * common/ptid.c (null_ptid, minus_one_ptid, ptid_build) (pid_to_ptid, ptid_get_pid, ptid_get_lwp, ptid_get_tid) (ptid_equal, ptid_is_pid, ptid_lwp_p, ptid_tid_p): Replace describing comments with references to ptid.h. * common/ptid.h: Remove intro description of constructors, accessors and predicates. (struct ptid): Reformat. (minus_one_ptid, ptid_build, pid_to_ptid, ptid_get_pid) (ptid_get_lwp, ptid_get_tid, ptid_equal, ptid_is_pid): Change describing comments. --- gdb/common/ptid.c | 21 +++++++++-------- gdb/common/ptid.h | 65 +++++++++++++++++++++-------------------------------- 2 files changed, 37 insertions(+), 49 deletions(-) diff --git a/gdb/common/ptid.c b/gdb/common/ptid.c index e8d25c0..d7780d3 100644 --- a/gdb/common/ptid.c +++ b/gdb/common/ptid.c @@ -19,11 +19,12 @@ #include "ptid.h" -/* Oft used ptids */ +/* See ptid.h for these. */ + ptid_t null_ptid = { 0, 0, 0 }; ptid_t minus_one_ptid = { -1, 0, 0 }; -/* Create a ptid given the necessary PID, LWP, and TID components. */ +/* See ptid.h. */ ptid_t ptid_build (int pid, long lwp, long tid) @@ -36,7 +37,7 @@ ptid_build (int pid, long lwp, long tid) return ptid; } -/* Create a ptid from just a pid. */ +/* See ptid.h. */ ptid_t pid_to_ptid (int pid) @@ -44,7 +45,7 @@ pid_to_ptid (int pid) return ptid_build (pid, 0, 0); } -/* Fetch the pid (process id) component from a ptid. */ +/* See ptid.h. */ int ptid_get_pid (ptid_t ptid) @@ -52,7 +53,7 @@ ptid_get_pid (ptid_t ptid) return ptid.pid; } -/* Fetch the lwp (lightweight process) component from a ptid. */ +/* See ptid.h. */ long ptid_get_lwp (ptid_t ptid) @@ -60,7 +61,7 @@ ptid_get_lwp (ptid_t ptid) return ptid.lwp; } -/* Fetch the tid (thread id) component from a ptid. */ +/* See ptid.h. */ long ptid_get_tid (ptid_t ptid) @@ -68,7 +69,7 @@ ptid_get_tid (ptid_t ptid) return ptid.tid; } -/* ptid_equal() is used to test equality of two ptids. */ +/* See ptid.h. */ int ptid_equal (ptid_t ptid1, ptid_t ptid2) @@ -78,7 +79,7 @@ ptid_equal (ptid_t ptid1, ptid_t ptid2) && ptid1.tid == ptid2.tid); } -/* Returns true if PTID represents a process. */ +/* See ptid.h. */ int ptid_is_pid (ptid_t ptid) @@ -90,7 +91,7 @@ ptid_is_pid (ptid_t ptid) return (ptid_get_lwp (ptid) == 0 && ptid_get_tid (ptid) == 0); } -/* Returns true if PTID represents a lwp. */ +/* See ptid.h. */ int ptid_lwp_p (ptid_t ptid) @@ -102,7 +103,7 @@ ptid_lwp_p (ptid_t ptid) return (ptid_get_lwp (ptid) != 0); } -/* Returns true if PTID represents a tid. */ +/* See ptid.h. */ int ptid_tid_p (ptid_t ptid) diff --git a/gdb/common/ptid.h b/gdb/common/ptid.h index 1326506..2a31a1c 100644 --- a/gdb/common/ptid.h +++ b/gdb/common/ptid.h @@ -20,69 +20,56 @@ #ifndef PTID_H #define PTID_H -/* The ptid struct is a collection of the various "ids" necessary - for identifying the inferior. This consists of the process id - (pid), thread id (tid), and other fields necessary for uniquely - identifying the inferior process/thread being debugged. When - manipulating ptids, the constructors, accessors, and predicates - declared in this file should be used. These are as follows: - - ptid_build - Make a new ptid from a pid, lwp, and tid. - pid_to_ptid - Make a new ptid from just a pid. - ptid_get_pid - Fetch the pid component of a ptid. - ptid_get_lwp - Fetch the lwp component of a ptid. - ptid_get_tid - Fetch the tid component of a ptid. - ptid_equal - Test to see if two ptids are equal. - ptid_is_pid - Test if a ptid is of the form (pid, 0, 0). - ptid_lwp_p - Test if a ptid's lwp component is non-zero. - ptid_tid_p - Test if a ptid's tid component is non-zero. - - Please do NOT access the struct ptid members directly (except, of - course, in the implementation of the above ptid manipulation - functions). */ +/* The ptid struct is a collection of the various "ids" necessary for + identifying the inferior process/thread being debugged. This + consists of the process id (pid), lightweight process id (lwp) and + thread id (tid). When manipulating ptids, the constructors, + accessors, and predicates declared in this file should be used. Do + NOT access the struct ptid members directly. */ struct ptid - { - /* Process id */ - int pid; +{ + /* Process id. */ + int pid; - /* Lightweight process id */ - long lwp; + /* Lightweight process id. */ + long lwp; - /* Thread id */ - long tid; - }; + /* Thread id. */ + long tid; +}; typedef struct ptid ptid_t; /* The null or zero ptid, often used to indicate no process. */ extern ptid_t null_ptid; -/* The -1 ptid, often used to indicate either an error condition +/* The (-1,0,0) ptid, often used to indicate either an error condition or a "don't care" condition, i.e, "run all threads." */ extern ptid_t minus_one_ptid; -/* Attempt to find and return an existing ptid with the given PID, LWP, - and TID components. If none exists, create a new one and return - that. */ +/* Make a ptid given the necessary PID, LWP, and TID components. */ ptid_t ptid_build (int pid, long lwp, long tid); -/* Find/Create a ptid from just a pid. */ +/* Make a new ptid from just a pid. This ptid is usually used to + represent a whole process, including all its lwps/threads. */ ptid_t pid_to_ptid (int pid); -/* Fetch the pid (process id) component from a ptid. */ +/* Fetch the pid (process id) component from a ptid. */ int ptid_get_pid (ptid_t ptid); -/* Fetch the lwp (lightweight process) component from a ptid. */ +/* Fetch the lwp (lightweight process) component from a ptid. */ long ptid_get_lwp (ptid_t ptid); -/* Fetch the tid (thread id) component from a ptid. */ +/* Fetch the tid (thread id) component from a ptid. */ long ptid_get_tid (ptid_t ptid); -/* Compare two ptids to see if they are equal */ -int ptid_equal (ptid_t p1, ptid_t p2); +/* Compare two ptids to see if they are equal. */ +int ptid_equal (ptid_t ptid1, ptid_t ptid2); -/* Return true if PTID represents a process id. */ +/* Returns true if PTID represents a whole process, including all its + lwps/threads. Such ptids have the form of (pid,0,0), with pid != + -1. */ int ptid_is_pid (ptid_t ptid); /* Return true if PTID's lwp member is non-zero. */