From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id uDxkKUm+nmVwyjcAWB0awg (envelope-from ) for ; Wed, 10 Jan 2024 10:56:57 -0500 Authentication-Results: simark.ca; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=CVW2i694; dkim-atps=neutral Received: by simark.ca (Postfix, from userid 112) id A4D8A1E0C3; Wed, 10 Jan 2024 10:56:57 -0500 (EST) Received: from server2.sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 913BD1E092 for ; Wed, 10 Jan 2024 10:56:55 -0500 (EST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id B83D43861005 for ; Wed, 10 Jan 2024 15:56:54 +0000 (GMT) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id 6CDB8385E838 for ; Wed, 10 Jan 2024 15:55:05 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 6CDB8385E838 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 6CDB8385E838 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1704902107; cv=none; b=nYqbh2Cae54NLLB5LHr7jp0t+2QvHuimVuik55u2eo72dU4hpPHGnOkkGm1B5MIXbePOeQ+2Jomdfn+ihg34VzMM91+hgxBzpa35mSBieBv7Elci5ZZc+8YtOqRisQsQJeMbPZjeOHAhAmuO8tjfAtOlBGNaIZPxVtlDdNcFbf0= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1704902107; c=relaxed/simple; bh=qqkwLYzQ1segrGuHdfuln+pzPOl/PM6Kz75/8Sme4Cg=; h=DKIM-Signature:From:To:Subject:Date:Message-Id:MIME-Version; b=YOTldCo2YhOKVgXxMK+DMKpM+ZmPxGkXgMRjuXVbzO7VMmjWapJTn76NF6p68l0U+j75T5zqr5Ut6SU1VnfpTXjZCrn1xf0ALA0mVCz2EFT+g/3nxkzJ2FsqB61Q8t+kVZPcm8zpTrTuMbDJoTts5pbe10ZEwQE7qAKttwRZNcA= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1704902105; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=oTcBSyL9GfI7yV1i9lvEFTa9kbP4NmRLxWfmnzOZ7Ac=; b=CVW2i694352JKR8leJodgYy+ttd4FRt7lJlYKdZjuHuJysaE9yIwvFZXq660Ju1DSM4EXT KPws32F6OgxIv6UPDepxl4szcpEsp2PJ8o99Q9wKiAv4RJPXS06hrtvSsOOtnL1mUWQemX vJc9d/SptIMGLfO1lupPrs/iTitQEW8= Received: from mail-wr1-f72.google.com (mail-wr1-f72.google.com [209.85.221.72]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-656-4Y4vb8jIP7CD5YcQGRzLug-1; Wed, 10 Jan 2024 10:55:03 -0500 X-MC-Unique: 4Y4vb8jIP7CD5YcQGRzLug-1 Received: by mail-wr1-f72.google.com with SMTP id ffacd0b85a97d-3368698f0caso2608497f8f.1 for ; Wed, 10 Jan 2024 07:55:03 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704902101; x=1705506901; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=oTcBSyL9GfI7yV1i9lvEFTa9kbP4NmRLxWfmnzOZ7Ac=; b=XWapxZdDT1FOeiHlh3spLZgOyQXFEvomuPipOQFqnWbv9R7RdrXXw1Rj+nIdo0PFYA QfOouaDy5V3AG99DiP9pgdAS6fLZYJSoBk3voHECaDKMUPCxDM0oQPJcaE3KlVc3sDZd QPfqRw4sBkMjaOlcAoN79P+3Zp029azxX6JlP5B3pkvSkltQ2WlZKoAso8OvFxC/cLXI Fv+/NdJJ6lYngsuAX/Y955Lr6YI1epAmtuIv1FI5RIq7W4aiGxSS1UQs/YNSIuUVjeN8 71z+luJg6UIFRUd2srFo3mJx2YPyShSNRjLgqGGQWVZSiO1XLuWHX58C6PTyiXprca16 F++g== X-Gm-Message-State: AOJu0YyDytEFO/57eIsmeHZ6ttOe8HdW/h5wPaXQKoxr4pR54B+cLD0W c+ODD6zPcCggCnc3zEd2CmzmnEx5rzfKITEVODJ191pmn420Q29/0kNcY4he50QDL9CcZVGiiac vW3gB16j2igxdvapC0p6uqyPuhbcVCtWxjKzPu79i+RMaduU8nqaZx32z9yMHlMTSBlque/VtuA NFDsMuBAqK2/+O/A== X-Received: by 2002:a5d:52c5:0:b0:337:6123:ca34 with SMTP id r5-20020a5d52c5000000b003376123ca34mr315994wrv.254.1704902101582; Wed, 10 Jan 2024 07:55:01 -0800 (PST) X-Google-Smtp-Source: AGHT+IGwF265NSG9w5Oj4Lv1LLnuoeNW5+QPANT+pM+KF36zqn27rid3C4pStZy25NOxlgztFXUn0A== X-Received: by 2002:a5d:52c5:0:b0:337:6123:ca34 with SMTP id r5-20020a5d52c5000000b003376123ca34mr315988wrv.254.1704902101240; Wed, 10 Jan 2024 07:55:01 -0800 (PST) Received: from localhost (185.223.159.143.dyn.plus.net. [143.159.223.185]) by smtp.gmail.com with ESMTPSA id cw16-20020a056000091000b0033753a61e96sm5198077wrb.108.2024.01.10.07.55.00 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 10 Jan 2024 07:55:00 -0800 (PST) From: Andrew Burgess To: gdb-patches@sourceware.org Cc: Andrew Burgess Subject: [PATCHv2 7/8] gdb/doc: add some notes on selecting suitable attribute names Date: Wed, 10 Jan 2024 15:54:44 +0000 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="US-ASCII"; x-default=true X-Spam-Status: No, score=-13.0 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gdb-patches-bounces+public-inbox=simark.ca@sourceware.org In previous commits I've added Object.__dict__ support to gdb.Inferior and gdb.InferiorThread, this is similar to the existing support for gdb.Objfile and gdb.Progspace. This commit extends the documentation to offer the user some guidance on selecting good names for their custom attributes so they can (hopefully) avoid conflicting with any future attributes that GDB might add. The rules I've proposed are: 1. Don't start user attributes with a lower case letter, all the current GDB attributes start with a lower case letter, and I suspect all future attributes would also start with a lower case letter, and 2. Don't start user attributes with a double underscore, this risks conflicting with Python built in attributes (e.g. __dict__) - though clearly the user would need to start and end with a double underscore, but it seemed easier just to say no double underscores. I'm doing this as a separate commit as I've updated the docs for the existing gdb.Objfile and gdb.Progspace so they all reference a single paragraph on selecting attribute names. --- gdb/doc/python.texi | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 2eed332fe59..40803274a27 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -3671,6 +3671,13 @@ usual Python way. This is useful if, for example, one needs to do some extra record keeping associated with the inferior. +@anchor{choosing attribute names} +When selecting a name for a new attribute, avoid starting the new +attribute name with a lower case letter; future attributes added by +@value{GDBN} will start with a lower case letter. Additionally, avoid +starting attribute names with two underscore characters, as these +could clash with Python builtin attribute names. + In this contrived example we record the time when an inferior last stopped: @@ -4181,6 +4188,9 @@ in the usual Python way. This is useful if, for example, one needs to do some extra record keeping associated with the thread. +See @ref{choosing attribute names} for guidance on selecting a +suitable name for new attributes. + In this contrived example we record the time when a thread last stopped: @@ -5396,6 +5406,9 @@ This is useful if, for example, one needs to do some extra record keeping associated with the program space. +See @ref{choosing attribute names} for guidance on selecting a +suitable name for new attributes. + In this contrived example, we want to perform some processing when an objfile with a certain symbol is loaded, but we only want to do this once because it is expensive. To achieve this we record the results @@ -5556,6 +5569,9 @@ This is useful if, for example, one needs to do some extra record keeping associated with the objfile. +See @ref{choosing attribute names} for guidance on selecting a +suitable name for new attributes. + In this contrived example we record the time when @value{GDBN} loaded the objfile. -- 2.25.4