From patchwork Wed Oct 27 22:59:51 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 14371 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 46526BF415 for ; Wed, 27 Oct 2021 23:00:24 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 8450C6487F; Thu, 28 Oct 2021 01:00:23 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="IuztqUbK"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id BF21D60128 for ; Thu, 28 Oct 2021 01:00:20 +0200 (CEST) Received: from pendragon.lan (62-78-145-57.bb.dnainternet.fi [62.78.145.57]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 38D92276 for ; Thu, 28 Oct 2021 01:00:20 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1635375620; bh=Mf/EdA/o8PdOcHIRVKRqw0fmk7IFzN+mdFfG6TXbCUw=; h=From:To:Subject:Date:From; b=IuztqUbK32QEj1XVqxOLft6U2iTbGxF/HiqHxXAeNs26UH4I/dVoElQaiD/dXf2Ea 2K7DY7SVM6Nk1IbTZRKyLqzDIIEUYzm+kghjAS72MD57LrgXVhkq4igKuCHNLsUbTA FdPqgjJwCmuZklZg2RZl2sD7fDqkAP7YlhkHTCRc= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Date: Thu, 28 Oct 2021 01:59:51 +0300 Message-Id: <20211027225951.10578-1-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.32.0 MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH] Documentation: coding-style: Document error handling rules X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Following a conversation on the mailing list about the use of assertions, document the error handling strategy in libcamera. This is an initial set of rules that are expected be extended and detailed in the future. Signed-off-by: Laurent Pinchart Reviewed-by: Kieran Bingham --- Documentation/coding-style.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) base-commit: 76bd9f3d80cb99a3391832b644b65a619427ed00 diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst index ef3a0d1714ab..4e8d6988fef8 100644 --- a/Documentation/coding-style.rst +++ b/Documentation/coding-style.rst @@ -217,6 +217,36 @@ global variable, should run a minimal amount of code in the constructor and destructor, and code that contains dependencies should be moved to a later point in time. +Error Handling +~~~~~~~~~~~~~~ + +Proper error handling is crucial to the stability of libcamera. The project +follows a set of high-level rules: + +* Make errors impossible through API design. The best way to handle errors is + to prevent them from happening in the first place. The preferred option is + thus to prevent error conditions at the API design stage when possible. +* Detect errors at compile time. Compile-test checking of errors not only + reduces the runtime complexity, but also ensures that errors are caught early + on during development instead of during testing or, worse, in production. The + static_assert() declaration should be used where possible for this purpose. +* Validate all external API contracts. Explicit pre-condition checks shall be + used to validate API contracts. Whenever possible, appropriate errors should + be returned directly. As libcamera doesn't use exceptions, errors detected in + constructors shall result in the constructed object being marked as invalid, + with a public member function available to check validity. The checks should + be thorough for the public API, and may be lighter for internal APIs when + pre-conditions can reasonably be considered to be met through other means. +* Use assertions for fatal issues only. The ASSERT() macro causes a program + abort when compiled in debug mode, and is a no-op otherwise. It is useful to + abort execution synchronously with the error check instead of letting the + error cause problems (such as segmentation faults) later, and to provide a + detailed backtrace. Assertions shall only be used to catch conditions that are + never supposed to happen without a serious bug in libcamera that would prevent + safe recovery. They shall never be used to validate API contracts. The + assertion conditions shall not cause any side effect as they are compiled out + in non-debug mode. + C Compatibility Headers ~~~~~~~~~~~~~~~~~~~~~~~