From patchwork Mon Dec 7 22:19:45 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: morganamilo X-Patchwork-Id: 1822 Return-Path: Delivered-To: patchwork@archlinux.org Received: from apollo.archlinux.org (localhost [127.0.0.1]) by apollo.archlinux.org (Postfix) with ESMTP id 2CCD21C99763C for ; Mon, 7 Dec 2020 22:41:41 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on apollo.archlinux.org X-Spam-Level: X-Spam-Status: No, score=-1.1 required=5.0 tests=DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1,DKIM_VALID=-0.1,DKIM_VALID_AU=-0.1, MAILING_LIST_MULTI=-1,RCVD_IN_MSPIKE_H4=-0.01,RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_PASS=-0.001,T_DMARC_POLICY_NONE=0.01 autolearn=ham autolearn_force=no version=3.4.4 X-Spam-BL-Results: [127.0.0.19] Received: from mail.archlinux.org (mail.archlinux.org [95.216.189.61]) by apollo.archlinux.org (Postfix) with ESMTPS for ; Mon, 7 Dec 2020 22:41:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=archlinux.org; s=luna2; t=1607379739; bh=lu28HHZNO8hp24dUfdxCyWYfMzlfqHcFtbgZRENdma0=; h=From:To:Date:In-Reply-To:References:Subject:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: Reply-To; b=pwPxNM55nVtttUnotBZe1n9z2c5CcLdWOHQErwZXaGNrqGe1EJwTKBl/Ramu0ISZW TLAt0GjuPxZ06xvSSmGpxl/fLbHCJ81pViyJeptQGZoEHzI2ASP+Me3JrJF/gq6IAn gKrgm2YZPdQKxLzPdMOOjkIRctZrqjRquMB4owX5GABiq5S+c9adHQOFzbXhxl951D m8EQELWgvadQVAvxJPJsOOaRJnzeAoz4T3jcrakEWrcbf/F5qt1PKE0CYNV3t7Mn8s 6f0yC4uNS1ljYkLQrqcckCaJmjCf9IaPKyCIsS9c6aK5JUmHShrOaax90IuMy1kldf O83Qqj8IcMkB5prL+pF19A19BLjkCSi9OPmxZnbkKuz/5sSuVk+eJUX3sbrXaeEHGv kiZ23O8y7gg0WnzdyTpwKEmeiv2a1hriFnOeklqoX/qFVhSXP0FGEUkZFiHpfYlFaB sJar62+f80iR7yCm6KIrkToWU87m0DRBwUIGnE2TmoFUHMb7cciB00qBTpFtn1MnBB S50ge3bwCCrSZ1jMWCS4p5FkSLMCfUnc/Z4jPJM89rP3WSKj91dQ+nsO2VyYUtlt3S C1yktqbEsjag5MAB6plm9/RBbkXtYKFQqF9DYuAuazgK0D8v/VCRwJk/YHY+VU794g jjJOao6WTMDn4403Fttjt6Sc= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-rsa; t=1607380891; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=3ksxaf2/Bxd1FPOpToL8CTq6bTE048PTOoPSChsOabQ=; b=K1D9WVOZtdRz0VyS3+vddAV8esfjtHGE5W6tGNib9KFVg9/0veU7DmAjWCX45cULpbaRxV HLeymDDm1pQURsfqQqs9BgpeTzFIm+AwmmOKwj3/qlEKuQdxRk2M0cA6HKUX3dEyqPpwIb HBzLDW8VqcJ4dRylKgD+bimxDrrZkRclLGS5+Zz0TdkT8pWyymNyB4uIP9ETkvYLr5Chld bwJu0hmXVW8pATtRyG+s65Yw47ANS3A9lBWaReYXOpZWSvGiWSO/SWLcoBpyl/TmGeXZZb SjVMlWsv8hVgbuJOeooGyWZnlLo2dJq5+y/wC8CObA6QupqtfEniE9rLbRqJPDW79rsLIy izHdmiJhOTf0Dnih0NHwT+xbSwKXouWemac0iexHYMVWtsw7igCD8g9duaG1wtXqFVC65e 3afI+rfTePWaDi+LkrzoL6/115MNm9Ws1Xt/colcqMQCSPv1Ga9SQhJ25xBQk5y+XHsV5D Q8Lq8UX7YedRirr5XYqCX5fE14GYevHHQTmISD5TS+spl0zbYXhZ28zmF2GsVSJSG51OSi 1v4q2w2F8S9/ESq/w8Tg/95WEnjOxlO3UpZuVoEzUicXyhDMZnRvwAdFyOj6O0mdP66oVW XUmxW4aJjZj4WOOc1dftJ0svx2/n6BQKsdqSX69bBA3x+Nq0OEZPc= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-ed25519; t=1607380891; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=3ksxaf2/Bxd1FPOpToL8CTq6bTE048PTOoPSChsOabQ=; b=qwv0zNIbKMr/COtljmJcoMCF6Bos8ibzJzH9Bu2IperobajpyD0c2Ydx1FUFL76ro5gpKa 9zvjH8wxjiWN4sDQ== From: morganamilo DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-rsa; t=1607379733; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=3ksxaf2/Bxd1FPOpToL8CTq6bTE048PTOoPSChsOabQ=; b=s5BdtxdTnOkloSHTKnngv3Lf/gQlOQMGgTvnAbgTvL8FbKwsViXLhcjH9VgdcgVG9tOFKx gEOvVMtlyC4unrh5GuHUtAY2niH36jBppxBnmu3bb+A/S3tzc21mDoabda2r6ZRPSl8bDt OMbDszvu1SRHsmt/KG8pEZLdnrEeUlGao+v8Xj5R3pLpwZAVIzLpBtFgiOGfC2Pg3n+Bq9 WmTzJlj9efqDpi/IuMTyGQgsj2ms8ZWpc+KdeMKrsbjAE64WEN1+0gzlGBlbbbokvZdXom 2Hy9FjwOAb+6186YUJMJHu+sza1ZJ9Vs6/Cqi7LxnX5BgKB+/TtilIC9idsEcuGa8e3DYa w3zqU+KGcfawfQsbhJNdEGFx9bzmBHlt6k9VBQvRT/2O0zn7PqoZ5SdlFZuluc15IULc7I dEcMfukFlHwPnV37IDSelyYmOi8r6afyPvE03l7tPedtfJVPTpg4dXOQVNfH5FyRfES8qy /b8mMFAfMIADWQJdZWraPZ8jJs2HzlNreRE4AFEPApyIhiUZeiLXkD+kYJ1dvCd/UbbHU7 gZSntv6nXQIc0ieTCYhCiEJFkuz28x9qyC1TheqfUa0xLx3V2l1abMAe3zb/zrtmDEeMAC oh5HnpBvvXQVZ8ssS7jQbY323U9/qwojVjgrONfWFiCiTSVkyl3TI= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-ed25519; t=1607379733; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=3ksxaf2/Bxd1FPOpToL8CTq6bTE048PTOoPSChsOabQ=; b=41aaAr/aFz/pOpl0tl4QmqFg67+btKkWLqEzohnZg2Dc1BMYJ3IZtIf0+AcuMYhXXuQBL0 5hCGQ9631ukp65DA== To: pacman-dev@archlinux.org Date: Mon, 7 Dec 2020 22:19:45 +0000 Message-Id: <20201207221956.667322-13-morganamilo@archlinux.org> X-Mailer: git-send-email 2.29.2 In-Reply-To: <20201207221956.667322-1-morganamilo@archlinux.org> References: <20201207221956.667322-1-morganamilo@archlinux.org> MIME-Version: 1.0 Subject: [pacman-dev] [PATCH 12/23] doc: document transactions X-BeenThere: pacman-dev@archlinux.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Discussion list for pacman development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Discussion list for pacman development Errors-To: pacman-dev-bounces@archlinux.org Sender: "pacman-dev" Authentication-Results: mail.archlinux.org; auth=pass smtp.auth=luna smtp.mailfrom=pacman-dev-bounces@archlinux.org --- lib/libalpm/alpm.h | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 30bfb06d..76ae5722 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -2068,18 +2068,26 @@ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive); /* End of alpm_packages */ /** @} */ - -/* - * Sync - */ - /** Check for new version of pkg in sync repos * (only the first occurrence is considered in sync) */ alpm_pkg_t *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync); -/** @addtogroup alpm_api_trans Transaction Functions - * Functions to manipulate libalpm transactions +/** @addtogroup alpm_trans Transaction + * @brief Functions to manipulate libalpm transactions + * + * Transactions are the way to add/remove packages to/from the system. + * Only one transaction can exist at a time. + * + * The basic workflow of a transaction is to: + * + * - Initialize with \link alpm_trans_init \endlink + * - Choose which packages to add with \link alpm_add_pkg \endlink and \link alpm_remove_pkg \endlink + * - Prepare the transaction with \link alpm_trans_prepare \endlink + * - Commit the transaction with \link alpm_trans_commit \endlink + * - Release the transaction with \link alpm_trans_release \endlink + * + * A transaction can be released at any time. A transaction does not have to be committed. * @{ */ @@ -2172,10 +2180,11 @@ int alpm_trans_interrupt(alpm_handle_t *handle); * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_trans_release(alpm_handle_t *handle); -/** @} */ -/** @name Common Transactions */ -/** @{ */ +/** @name Add/Remove packages + * These functions remove/add packages to the transactions + * @{ + * */ /** Search for packages to upgrade and add them to the transaction. * @param handle the context handle @@ -2186,22 +2195,24 @@ int alpm_sync_sysupgrade(alpm_handle_t *handle, int enable_downgrade); /** Add a package to the transaction. * If the package was loaded by alpm_pkg_load(), it will be freed upon - * alpm_trans_release() invocation. + * \link alpm_trans_release \endlink invocation. * @param handle the context handle * @param pkg the package to add * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_add_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg); -/** Add a package removal action to the transaction. +/** Add a package removal to the transaction. * @param handle the context handle * @param pkg the package to uninstall * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg); +/* End of add/remove packages */ /** @} */ +/* End of alpm_trans */ /** @} */ /*