From patchwork Wed Jul 24 11:05:22 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Patrick Steinhardt X-Patchwork-Id: 13740851 Received: from fhigh2-smtp.messagingengine.com (fhigh2-smtp.messagingengine.com [103.168.172.153]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E2713156F48 for ; Wed, 24 Jul 2024 11:05:26 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=103.168.172.153 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1721819128; cv=none; b=S3/R9Q6jHEwrFiL+0wZnIgIUjdOlCPGLipQHrM5k7HiuUSfAJvATHYc+fG39mTRQxGhx0zaY8bpTAkIPa8f42PFenWFp3Z+GUrMdD5nKoQOYXnrMcluvvTKwmNhT92ratzlwcoPQQ8kDCEJbDn8jXr0ZDcTrRqXAy6cw22HI8QY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1721819128; c=relaxed/simple; bh=egUvbGY+ME57I0AcHEgBfXxcx008Y4PnUammvkuHHbk=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=WI4y2+6UMDkFGFRRBRwFPSNiAkfBZ+KkCz2faKroyOTk5NfuYwktxuJwio6mc5IFknOUXGt/dIDgeH4hcaxnNQBvnEAQnLjSFeqAi/8EMKIOjrLVwFrTka+WK1LobletTVvP6uz6ddZqZNBcTZkispctYd6DoIgJna9ViFgFzZk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im; spf=pass smtp.mailfrom=pks.im; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b=DIzFTxmc; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=JI8GKDNW; arc=none smtp.client-ip=103.168.172.153 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pks.im Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b="DIzFTxmc"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="JI8GKDNW" Received: from compute8.internal (compute8.nyi.internal [10.202.2.227]) by mailfhigh.nyi.internal (Postfix) with ESMTP id 9B2C71140256; Wed, 24 Jul 2024 07:05:25 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute8.internal (MEProxy); Wed, 24 Jul 2024 07:05:25 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pks.im; h=cc:cc :content-type:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:subject :subject:to:to; s=fm3; t=1721819125; x=1721905525; bh=VkDrViGblX xKU5Kqnj1AFzTsw1oEgKpqoeaGw2/8Cq8=; b=DIzFTxmc0PnlPY9Q5lNjEHPZrb ZWns10MLxVFHFEF7+2KWiC7n2uCd43ybprG8TLNzwQd+2sMy9q2tZIDyyMOvUtZx vrUTsaqSCU+mr8InZu2rpj+oKvP2PeoF/LkP963+/w3+5jlkFJShhsRj60E6alxV 7JoOIv5I+BKfjXjKQi5YYWXvaqYvGwej5dgPmxJcZsTINgvKkriq6z+HTZyJtskt mLxUdOVi+nqGVWwt18+/j4FCWt2w3iq6O3oCEYmgIvY3pvaJ4PCc5edVCdglN9XC dW1M6UJn+Ib19imtkHQhaD96hAKlwQSoE1DC2UKpUJmSn+gpoDgLi/q9IAHg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:subject:subject:to :to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1721819125; x=1721905525; bh=VkDrViGblXxKU5Kqnj1AFzTsw1oE gKpqoeaGw2/8Cq8=; b=JI8GKDNWRTvXy82mRsFALKqMNdxwJhqzHRpodNDjEePz FUosq+qvMUEl3xb/1K9zi8H3L8Ox32BrwggeJY2lC7lkgTQ6FBYx0g8hQRtOyjUh T5P3yWmAxdgsrySJS98Pg2jGvICdYxy2ON/FPfX/E1TPVcoHKZoXUal9orTEb9UA +lj4jy+eSzcbTdP0hmsYUDZ2xhKK8VrQKPA1EJuB7bHHZAslrQd/XYRg3S1AyPFQ Hgs6bes6uHi9fyGQKGEsfanWyZqyPAmnvUUsX9lnr2YTaO3r8N85VhY5mERasM/4 23UPSVPGEYxY/TGnEhQ7xp764AUCiLJmGyHsPZIrzA== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddriedugdefiecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpeffhffvvefukfhfgggtuggjsehgtderredttddvnecuhfhrohhmpefrrghtrhhi tghkucfuthgvihhnhhgrrhguthcuoehpshesphhkshdrihhmqeenucggtffrrghtthgvrh hnpeeukedtvedtffevleejtefgheehieegkeeluddvfeefgeehgfeltddtheejleffteen ucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehpshesph hkshdrihhmpdhnsggprhgtphhtthhopedt X-ME-Proxy: Feedback-ID: i197146af:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Wed, 24 Jul 2024 07:05:24 -0400 (EDT) Received: by localhost (OpenSMTPD) with ESMTPSA id f93409d3 (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Wed, 24 Jul 2024 11:04:08 +0000 (UTC) Date: Wed, 24 Jul 2024 13:05:22 +0200 From: Patrick Steinhardt To: git@vger.kernel.org Cc: Karthik Nayak Subject: [PATCH 3/3] Documentation: document difference between release and free Message-ID: <5e1de3c3159968e897a83c05dae5e8504d37a16c.1721818488.git.ps@pks.im> References: Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: We semi-regularly have discussions around whether a function shall be named `release()` or `free()`. For most of the part we use these two terminologies quite consistently though: - `release()` only frees internal state of a structure, whereas the structure itself is not free'd. - `free()` frees both internal state and the structure itself. Carve out a space where we can add idiomatic names for common functions in our coding guidelines. This space can get extended in the future when we feel the need to document more idiomatic names. Signed-off-by: Patrick Steinhardt --- Documentation/CodingGuidelines | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 34fcbcb5a4..ace4c4ad0c 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -560,6 +560,18 @@ For C programs: void reset_strbuf(struct strbuf *buf); + - There are several common idiomatic names for functions performing + specific tasks on structures: + + - `_init()` initializes a structure without allocating the + structure itself. + + - `_release()` releases a structure's contents without + freeing the structure. + + - `_free()` releases a structure's contents and frees the + structure. + For Perl programs: - Most of the C guidelines above apply.