From patchwork Wed Oct 12 18:52:24 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jeff Hostetler X-Patchwork-Id: 13005369 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 65514C4332F for ; Wed, 12 Oct 2022 18:52:39 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229967AbiJLSwh (ORCPT ); Wed, 12 Oct 2022 14:52:37 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58328 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229956AbiJLSwg (ORCPT ); Wed, 12 Oct 2022 14:52:36 -0400 Received: from mail-wr1-x42f.google.com (mail-wr1-x42f.google.com [IPv6:2a00:1450:4864:20::42f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D6DDFE070C for ; Wed, 12 Oct 2022 11:52:34 -0700 (PDT) Received: by mail-wr1-x42f.google.com with SMTP id j7so27542359wrr.3 for ; Wed, 12 Oct 2022 11:52:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=cTLoZaZ6n+Wz/7kdysCOtNZST9K2cELlvFYvnhYh5CM=; b=KPPdok5zjzNPtRh6FyTkBUyfMPtVXUNLtyHcLvEGnBvuFyvFINonzessWq7UO8lnnK Okqp18ZF+kZ15bitfYBrkU4hmFF36V5OziYPAoI+KntxPgSHJD6SIXI2psVcVjySEx+D B0SKffZ97HshKHbDNItjXFtePnDiXoly2QO9GsS6K5YldDQuKJvDM8Uy4b+VtAGmYpY2 ojxpGep1dDaqkFxq4Z8chAB+AFamcn5asDHQKsnPs8PQ3VOaz+qVud4kFepQ+UmXZO8q ZGYSDCUTsHW1Bs1e+DlbK+nk1ZwCqq16OH6epNPs3bT3eclvGQi1xs+AOwJF6cwZVXA4 wU7g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=cTLoZaZ6n+Wz/7kdysCOtNZST9K2cELlvFYvnhYh5CM=; b=qUSphNkLoXIrLVyRf7aMnwMO1Dwb8uO61XtBsDXZNAZxO2+gDsiM+xg2fBcA8Ry2vH QvydP9myGK+lu0VcZXaA2jddrIbRCCPlADHkoinjbYqAVXWLk40byS2hThUMOMVRAvFO 5yY4DnLtpnO9S0Eaef5yrqSVmPTiT240gXz2ZUhYdk6fOtrcBNVPtE826rGa/Khq74PC Q77F9gCUUZM77mY6S+Ob3f8KbPRqd1Ud73xpi3VfklqmvnE8MoCgNe5/N6W6k4wbPoem HVeBgFwgOKPlQ1w5tlwJpiGulSuWComv0sPoLUNs2yDrrxlk6gdCmmhm8NqsBoTQZQS3 H07A== X-Gm-Message-State: ACrzQf33OVJUNNo57ZkGMNRn0+4PQ+SDtkPFvLSsI3V4CuxlQU0/qWeN pLZODNdMoyGBhcdKd95TLYXuGl6N7/k= X-Google-Smtp-Source: AMsMyM4WGTHXiwo0y4RtwEWRHasaw6GS8LPZpqwQgY1alkxvMQwqj8JPyBmWjN8dmVTg4KpaIFPI7Q== X-Received: by 2002:a5d:43c8:0:b0:22e:632a:9bbf with SMTP id v8-20020a5d43c8000000b0022e632a9bbfmr18553851wrr.481.1665600753234; Wed, 12 Oct 2022 11:52:33 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id c9-20020adfe709000000b0022add371ed2sm338956wrm.55.2022.10.12.11.52.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 12 Oct 2022 11:52:32 -0700 (PDT) Message-Id: <6e7e4f3187e2fbbbb54bb1cf5793bf6e981a5a94.1665600750.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 12 Oct 2022 18:52:24 +0000 Subject: [PATCH v2 1/7] trace2: use size_t alloc,nr_open_regions in tr2tls_thread_ctx Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsA==?= Bjarmason , Jeff Hostetler , Derrick Stolee , Jeff Hostetler , Jeff Hostetler Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Jeff Hostetler From: Jeff Hostetler Use "size_t" rather than "int" for the "alloc" and "nr_open_regions" fields in the "tr2tls_thread_ctx". These are used by ALLOC_GROW(). Signed-off-by: Jeff Hostetler --- trace2/tr2_tls.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/trace2/tr2_tls.h b/trace2/tr2_tls.h index b1e327a928e..a90bd639d48 100644 --- a/trace2/tr2_tls.h +++ b/trace2/tr2_tls.h @@ -11,8 +11,8 @@ struct tr2tls_thread_ctx { struct strbuf thread_name; uint64_t *array_us_start; - int alloc; - int nr_open_regions; /* plays role of "nr" in ALLOC_GROW */ + size_t alloc; + size_t nr_open_regions; /* plays role of "nr" in ALLOC_GROW */ int thread_id; }; From patchwork Wed Oct 12 18:52:25 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jeff Hostetler X-Patchwork-Id: 13005371 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3A33CC4332F for ; Wed, 12 Oct 2022 18:52:42 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229971AbiJLSwl (ORCPT ); Wed, 12 Oct 2022 14:52:41 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58344 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229961AbiJLSwh (ORCPT ); Wed, 12 Oct 2022 14:52:37 -0400 Received: from mail-wm1-x32f.google.com (mail-wm1-x32f.google.com [IPv6:2a00:1450:4864:20::32f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 13864F4189 for ; Wed, 12 Oct 2022 11:52:36 -0700 (PDT) Received: by mail-wm1-x32f.google.com with SMTP id az22-20020a05600c601600b003c6b72797fdso1794629wmb.5 for ; Wed, 12 Oct 2022 11:52:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=iACA4FL6FLxqM8Gf+IfWNEBZzWlEQwVqQ42PnqkGRwo=; b=RjYDFAEPqEHw/nWs+VCqQDRvtmcE0W0Ti+MUyT4N0jFiNLOmJRzzxl7wBrrWmG7Wqz j1IajnBUkV7/V6XECvM7Mpo5wk8ecR6H29gRyIs31UDOxVwtwGWsKoEOPQ0k6VF1J0UO IEHmbFjTAjDXNnuE9adU7sBA83j19TcyZT5gFFdBkewR+0eNPNRt3FBzAJHHQKSd414K QdDJ2XKASUvU57RwufhL+jWO5LgGmWfx8MaaYpC4X2fQ/ADmSilTT5sBblpbtnjp4TPM lHPAX4/rC2Q1FedWb46DQItiUYobjdOdU720JZb+IHq7gYvLgr4xqbHlp5soY72OElEa QEGg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=iACA4FL6FLxqM8Gf+IfWNEBZzWlEQwVqQ42PnqkGRwo=; b=RgsG8wTrclCWAjZUhz/61+2M/cA6XnYlXySS/Z7lvyqZUmziFtPilpmDiTE4ttZdog oNVg0k1uj/032RGr9dKlz6c0CpTXY8UQalESPKwvpeIWZM/xJEUVe28WmDbUyuoozVmR HoEtSHe5MIWFFGsJuxYJzfIXWHDEIK2pp8OIPwKXu0y5oQs0NyxZf+CsvCYQzS1SExU/ pHmd20127ohCToAheyVhTMNYgROzTY4BMzf88dNFcIhgUM8K3NmbKi/2WjrdIdvqmx60 eDlc/KWVcJ47QeQmYnWHTdI8RiolA9yLuuIs+m4cAjglhp9EApV0fhcE8KW1St0yEDE8 3w2A== X-Gm-Message-State: ACrzQf1ZKduFSi5L0nWPZ+ZrCnxuIp9JLzQ8ErnN26thXCHQWAJoxws/ aqSif0UvaWnyPp1nwqKZg5+KBJLeh9s= X-Google-Smtp-Source: AMsMyM4HMgl9IYneBiQwfCxN6AH0iKmVuRTzRozb8tNlxGDxlzDHPPGR+HJBt7sSScBDhzr9sEfT2w== X-Received: by 2002:a05:600c:4385:b0:3b4:8fdd:ded6 with SMTP id e5-20020a05600c438500b003b48fddded6mr3766490wmn.127.1665600754302; Wed, 12 Oct 2022 11:52:34 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id bj30-20020a0560001e1e00b0022cd539ce5esm359944wrb.50.2022.10.12.11.52.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 12 Oct 2022 11:52:33 -0700 (PDT) Message-Id: <9dee7a75903936f086d97580441c776978d70b43.1665600750.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 12 Oct 2022 18:52:25 +0000 Subject: [PATCH v2 2/7] tr2tls: clarify TLS terminology Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsA==?= Bjarmason , Jeff Hostetler , Derrick Stolee , Jeff Hostetler , Jeff Hostetler Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Jeff Hostetler From: Jeff Hostetler Reduce or eliminate use of the term "TLS" in the Trace2 code. The term "TLS" has two popular meanings: "thread-local storage" and "transport layer security". In the Trace2 source, the term is associated with the former. There was concern on the mailing list about it refering to the latter. Update the source and documentation to eliminate the use of the "TLS" term or replace it with the phrase "thread-local storage" to reduce ambiguity. Signed-off-by: Jeff Hostetler --- Documentation/technical/api-trace2.txt | 8 ++++---- trace2.c | 2 +- trace2.h | 10 +++++----- trace2/tr2_tls.c | 6 +++--- trace2/tr2_tls.h | 18 +++++++++++------- 5 files changed, 24 insertions(+), 20 deletions(-) diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 2afa28bb5aa..431d424f9d5 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -685,8 +685,8 @@ The "exec_id" field is a command-unique id and is only useful if the `"thread_start"`:: This event is generated when a thread is started. It is - generated from *within* the new thread's thread-proc (for TLS - reasons). + generated from *within* the new thread's thread-proc (because + it needs to access data in the thread's thread-local storage). + ------------ { @@ -698,7 +698,7 @@ The "exec_id" field is a command-unique id and is only useful if the `"thread_exit"`:: This event is generated when a thread exits. It is generated - from *within* the thread's thread-proc (for TLS reasons). + from *within* the thread's thread-proc. + ------------ { @@ -1206,7 +1206,7 @@ worked on 508 items at offset 2032. Thread "th04" worked on 508 items at offset 508. + This example also shows that thread names are assigned in a racy manner -as each thread starts and allocates TLS storage. +as each thread starts. Config (def param) Events:: diff --git a/trace2.c b/trace2.c index 0c0a11e07d5..c1244e45ace 100644 --- a/trace2.c +++ b/trace2.c @@ -52,7 +52,7 @@ static struct tr2_tgt *tr2_tgt_builtins[] = * Force (rather than lazily) initialize any of the requested * builtin TRACE2 targets at startup (and before we've seen an * actual TRACE2 event call) so we can see if we need to setup - * the TR2 and TLS machinery. + * private data structures and thread-local storage. * * Return the number of builtin targets enabled. */ diff --git a/trace2.h b/trace2.h index 88d906ea830..af3c11694cc 100644 --- a/trace2.h +++ b/trace2.h @@ -73,8 +73,7 @@ void trace2_initialize_clock(void); /* * Initialize TRACE2 tracing facility if any of the builtin TRACE2 * targets are enabled in the system config or the environment. - * This includes setting up the Trace2 thread local storage (TLS). - * Emits a 'version' message containing the version of git + * This emits a 'version' message containing the version of git * and the Trace2 protocol. * * This function should be called from `main()` as early as possible in @@ -302,7 +301,8 @@ void trace2_exec_result_fl(const char *file, int line, int exec_id, int code); /* * Emit a 'thread_start' event. This must be called from inside the - * thread-proc to set up the trace2 TLS data for the thread. + * thread-proc to allow the thread to create its own thread-local + * storage. * * Thread names should be descriptive, like "preload_index". * Thread names will be decorated with an instance number automatically. @@ -315,8 +315,8 @@ void trace2_thread_start_fl(const char *file, int line, /* * Emit a 'thread_exit' event. This must be called from inside the - * thread-proc to report thread-specific data and cleanup TLS data - * for the thread. + * thread-proc so that the thread can access and clean up its + * thread-local storage. */ void trace2_thread_exit_fl(const char *file, int line); diff --git a/trace2/tr2_tls.c b/trace2/tr2_tls.c index 7da94aba522..8d2182fbdbb 100644 --- a/trace2/tr2_tls.c +++ b/trace2/tr2_tls.c @@ -69,9 +69,9 @@ struct tr2tls_thread_ctx *tr2tls_get_self(void) ctx = pthread_getspecific(tr2tls_key); /* - * If the thread-proc did not call trace2_thread_start(), we won't - * have any TLS data associated with the current thread. Fix it - * here and silently continue. + * If the current thread's thread-proc did not call + * trace2_thread_start(), then the thread will not have any + * thread-local storage. Create it now and silently continue. */ if (!ctx) ctx = tr2tls_create_self("unknown", getnanotime() / 1000); diff --git a/trace2/tr2_tls.h b/trace2/tr2_tls.h index a90bd639d48..1297509fd23 100644 --- a/trace2/tr2_tls.h +++ b/trace2/tr2_tls.h @@ -3,6 +3,12 @@ #include "strbuf.h" +/* + * Notice: the term "TLS" refers to "thread-local storage" in the + * Trace2 source files. This usage is borrowed from GCC and Windows. + * There is NO relation to "transport layer security". + */ + /* * Arbitry limit for thread names for column alignment. */ @@ -17,9 +23,7 @@ struct tr2tls_thread_ctx { }; /* - * Create TLS data for the current thread. This gives us a place to - * put per-thread data, such as thread start time, function nesting - * and a per-thread label for our messages. + * Create thread-local storage for the current thread. * * We assume the first thread is "main". Other threads are given * non-zero thread-ids to help distinguish messages from concurrent @@ -35,7 +39,7 @@ struct tr2tls_thread_ctx *tr2tls_create_self(const char *thread_name, uint64_t us_thread_start); /* - * Get our TLS data. + * Get the thread-local storage pointer of the current thread. */ struct tr2tls_thread_ctx *tr2tls_get_self(void); @@ -45,7 +49,7 @@ struct tr2tls_thread_ctx *tr2tls_get_self(void); int tr2tls_is_main_thread(void); /* - * Free our TLS data. + * Free the current thread's thread-local storage. */ void tr2tls_unset_self(void); @@ -81,12 +85,12 @@ uint64_t tr2tls_region_elasped_self(uint64_t us); uint64_t tr2tls_absolute_elapsed(uint64_t us); /* - * Initialize the tr2 TLS system. + * Initialize thread-local storage for Trace2. */ void tr2tls_init(void); /* - * Free all tr2 TLS resources. + * Free all Trace2 thread-local storage resources. */ void tr2tls_release(void); From patchwork Wed Oct 12 18:52:26 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jeff Hostetler X-Patchwork-Id: 13005372 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id AF6D6C4332F for ; Wed, 12 Oct 2022 18:52:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229977AbiJLSwn (ORCPT ); Wed, 12 Oct 2022 14:52:43 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58348 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229957AbiJLSwi (ORCPT ); Wed, 12 Oct 2022 14:52:38 -0400 Received: from mail-wr1-x42a.google.com (mail-wr1-x42a.google.com [IPv6:2a00:1450:4864:20::42a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 27D07E070A for ; Wed, 12 Oct 2022 11:52:37 -0700 (PDT) Received: by mail-wr1-x42a.google.com with SMTP id j7so27542494wrr.3 for ; Wed, 12 Oct 2022 11:52:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=bkJEMJFGS4hSCnUT3RbeMHEA6CGfHK7Uqd4sKFLXPuo=; b=Gv+RktFXz4tycKgrh9PelIgo40vZ0pRQ/tlQM9gTR4s4GFxHLDW2c1EA+2TewIEJiQ a7WBbpnBfOqBAAY7Z89epL2HCMQKZIpB2oKvoeoNkjfOo8xkzzomt5Z0EkgzdXAmQsHA f0t11eDO2V0kRLkFNVENrdWfKRmKyJFo2Pox5VYxky8rSOs1Hn//BKAOa4Xyh+MAtzEk WsHngbfkgkzPVhqNGH8zQpyySQ+dYnoBJiALPM1pCMX4wp2heOL6UwLfee4mdOrTGKap SvYylhJJe5nNyvhpB43P/eSv7n/lswFX3ykMMGfb4uGPXAiyJTvBPPqjTmUp6lWcQCEg i+Aw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=bkJEMJFGS4hSCnUT3RbeMHEA6CGfHK7Uqd4sKFLXPuo=; b=pj44x7ka1jFxf4sBWdaRwGAOzDLXhLmaSHvZRQPI46z9ahEUFw7s3UGpzXjTtUh7WM Wm1fZxae9i9+1+rS09OvHMuIP4sPFPNX+N9ehTFf4ZhAZOnHRosZWNojWCl1ZaXjqsLx 76AQGqGM97xQ7ugrnsTr9P9K5qBlI8nl1g7qLDdF05z0AGIV4siMxXyAArgCI5vaidKh qODjN06IUDVxJCcWA60ZYSEvIfpISZzQECRFFiozcIUUtd+yIvrqLKU092IYaZ9WAcYd sOrYEHrrjrJN7L12f41PPonZ9ua3uDEXDvp+VzIiD3Ael02oDnahhfCwjaa+eBjfGKlp IhQg== X-Gm-Message-State: ACrzQf1C5lAgPzCddQCxAtb2H1UuOPUFiWlbsvxBcQitfFogj85Go2wO 0vvhm1iVeuBU5lP+SXQRnI5np6Qrvxw= X-Google-Smtp-Source: AMsMyM5gEa25Q9ToOnuRsNNW/tpIdfIVCR72JVWnlpZmEv9cz9VtB2VInevDZzi9roebGq2OKWkQTQ== X-Received: by 2002:a05:6000:184e:b0:22e:4649:b3c9 with SMTP id c14-20020a056000184e00b0022e4649b3c9mr20319513wri.671.1665600755296; Wed, 12 Oct 2022 11:52:35 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id o9-20020a05600c510900b003a540fef440sm2773512wms.1.2022.10.12.11.52.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 12 Oct 2022 11:52:34 -0700 (PDT) Message-Id: <804dab9e1a7fa1cea9355bac92ada16332f1194e.1665600750.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 12 Oct 2022 18:52:26 +0000 Subject: [PATCH v2 3/7] api-trace2.txt: elminate section describing the public trace2 API Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsA==?= Bjarmason , Jeff Hostetler , Derrick Stolee , Jeff Hostetler , Jeff Hostetler Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Jeff Hostetler From: Jeff Hostetler Eliminate the mostly obsolete `Public API` sub-section from the `Trace2 API` section in the documentation. Strengthen the referral to `trace2.h`. Most of the technical information in this sub-section was moved to `trace2.h` in 6c51cb525d (trace2: move doc to trace2.h, 2019-11-17) to be adjacent to the function prototypes. The remaining text wasn't that useful by itself. Furthermore, the text would need a bit of overhaul to add routines that do not immediately generate a message, such as stopwatch timers. So it seemed simpler to just get rid of it. Signed-off-by: Jeff Hostetler --- Documentation/technical/api-trace2.txt | 61 +++----------------------- 1 file changed, 7 insertions(+), 54 deletions(-) diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 431d424f9d5..9d43909d068 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -148,20 +148,18 @@ filename collisions). == Trace2 API -All public Trace2 functions and macros are defined in `trace2.h` and -`trace2.c`. All public symbols are prefixed with `trace2_`. +The Trace2 public API is defined and documented in `trace2.h`; refer to it for +more information. All public functions and macros are prefixed +with `trace2_` and are implemented in `trace2.c`. There are no public Trace2 data structures. The Trace2 code also defines a set of private functions and data types in the `trace2/` directory. These symbols are prefixed with `tr2_` -and should only be used by functions in `trace2.c`. +and should only be used by functions in `trace2.c` (or other private +source files in `trace2/`). -== Conventions for Public Functions and Macros - -The functions defined by the Trace2 API are declared and documented -in `trace2.h`. It defines the API functions and wrapper macros for -Trace2. +=== Conventions for Public Functions and Macros Some functions have a `_fl()` suffix to indicate that they take `file` and `line-number` arguments. @@ -172,52 +170,7 @@ take a `va_list` argument. Some functions have a `_printf_fl()` suffix to indicate that they also take a `printf()` style format with a variable number of arguments. -There are CPP wrapper macros and `#ifdef`s to hide most of these details. -See `trace2.h` for more details. The following discussion will only -describe the simplified forms. - -== Public API - -All Trace2 API functions send a message to all of the active -Trace2 Targets. This section describes the set of available -messages. - -It helps to divide these functions into groups for discussion -purposes. - -=== Basic Command Messages - -These are concerned with the lifetime of the overall git process. -e.g: `void trace2_initialize_clock()`, `void trace2_initialize()`, -`int trace2_is_enabled()`, `void trace2_cmd_start(int argc, const char **argv)`. - -=== Command Detail Messages - -These are concerned with describing the specific Git command -after the command line, config, and environment are inspected. -e.g: `void trace2_cmd_name(const char *name)`, -`void trace2_cmd_mode(const char *mode)`. - -=== Child Process Messages - -These are concerned with the various spawned child processes, -including shell scripts, git commands, editors, pagers, and hooks. - -e.g: `void trace2_child_start(struct child_process *cmd)`. - -=== Git Thread Messages - -These messages are concerned with Git thread usage. - -e.g: `void trace2_thread_start(const char *thread_name)`. - -=== Region and Data Messages - -These are concerned with recording performance data -over regions or spans of code. e.g: -`void trace2_region_enter(const char *category, const char *label, const struct repository *repo)`. - -Refer to trace2.h for details about all trace2 functions. +CPP wrapper macros are defined to hide most of these details. == Trace2 Target Formats From patchwork Wed Oct 12 18:52:27 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jeff Hostetler X-Patchwork-Id: 13005373 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E41D5C433FE for ; Wed, 12 Oct 2022 18:52:46 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229980AbiJLSwp (ORCPT ); Wed, 12 Oct 2022 14:52:45 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58346 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229956AbiJLSwi (ORCPT ); Wed, 12 Oct 2022 14:52:38 -0400 Received: from mail-wr1-x42f.google.com (mail-wr1-x42f.google.com [IPv6:2a00:1450:4864:20::42f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E0AB9240A9 for ; Wed, 12 Oct 2022 11:52:36 -0700 (PDT) Received: by mail-wr1-x42f.google.com with SMTP id j7so27542536wrr.3 for ; Wed, 12 Oct 2022 11:52:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=eBYrCTm6sONYh2JzDxn3XUEMeP9cTr+K0XsOM99+7bc=; b=eqomppaclg8GvRuX5I6qMr9PObfalnG7n/gm3Vg6BLssYLwxicco0+q6JhMxxFngKc G0GJXaQESe+XGXHufnS8gpwyO2yD26i9F+JYH6YN0g1h7SaKBwE8VgYgZGf84DuiuvVA C+lRpIrg5QcDVNQ4hYW2RcFFbjueWr13dlNKGPVYLZJKqTwZrMnFQu//k69WxlB3n7wx 7WxHqxZIqoLYI1O07IuUbRKB/WuWSM+SjpiIOeDLRguuHaNjFvs3fCJFJrZJpvoYmMJq 1xTGATyDZrd5B9G7tTL0a/ID3Bd8037OPdgDACCVVgxCkV7By3Vl6ewcpA5QdrnkxrLa RqYQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=eBYrCTm6sONYh2JzDxn3XUEMeP9cTr+K0XsOM99+7bc=; b=uO0SKKB8V6+Ad4jC5+9CbC8E+odQWWnurXm21XXz3tsOLzHtvyahh/7anujr0dYSka ywilt3TRoVtFYYbYdD4hM1JtZVjpjRH6JPBpGoyEIq9XcPoZWAsEdVquCOccgC22IivX LILRs/vAYDKLBUxIGfg20crQ291FnSQF005GLq13AQom7TMAcpTjDq39YchCeCHhi5fX Ek2gWEKoezrbhpAfRFQwX6vTQ4GLPQzzKZKYRB2bNolgaL3cecK3DPGGDax7SvSpcXPI jJ9RCbQCvJJSIN/Js2GjeacRd2z/QLNGbgtsErSZxCUmwdyyMW33b529bfo50FB3TbOs ZQLw== X-Gm-Message-State: ACrzQf3bi6kVaypQBm8yp6idH/wA53f/qOdTt7x/khb5G8kts7UeJyxn Qve7jNnUtguVSkQw/7ocPayhEsWp3CY= X-Google-Smtp-Source: AMsMyM4WNQD1D+daoCmC/u4eXbZ5hoD5uvOnC39gJgAQpymADJEQRVFuYbyqtiNcSC4gZm8VypkAHA== X-Received: by 2002:adf:f501:0:b0:22c:cbea:240a with SMTP id q1-20020adff501000000b0022ccbea240amr19436213wro.78.1665600756255; Wed, 12 Oct 2022 11:52:36 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id az12-20020a05600c600c00b003a62052053csm2929327wmb.18.2022.10.12.11.52.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 12 Oct 2022 11:52:35 -0700 (PDT) Message-Id: <637b422b8606b3b6d954e6a1959aae450507cdfa.1665600750.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 12 Oct 2022 18:52:27 +0000 Subject: [PATCH v2 4/7] trace2: rename the thread_name argument to trace2_thread_start Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsA==?= Bjarmason , Jeff Hostetler , Derrick Stolee , Jeff Hostetler , Jeff Hostetler Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Jeff Hostetler From: Jeff Hostetler Rename the `thread_name` argument in `tr2tls_create_self()` and `trace2_thread_start()` to be `thread_base_name` to make it clearer that the passed argument is a component used in the construction of the actual `struct tr2tls_thread_ctx.thread_name` variable. The base name will be used along with the thread id to create a unique thread name. This commit does not change how the `thread_name` field is allocated or stored within the `tr2tls_thread_ctx` structure. Signed-off-by: Jeff Hostetler --- trace2.c | 6 +++--- trace2.h | 11 ++++++----- trace2/tr2_tls.c | 4 ++-- trace2/tr2_tls.h | 17 ++++++++++------- 4 files changed, 21 insertions(+), 17 deletions(-) diff --git a/trace2.c b/trace2.c index c1244e45ace..165264dc79a 100644 --- a/trace2.c +++ b/trace2.c @@ -466,7 +466,7 @@ void trace2_exec_result_fl(const char *file, int line, int exec_id, int code) file, line, us_elapsed_absolute, exec_id, code); } -void trace2_thread_start_fl(const char *file, int line, const char *thread_name) +void trace2_thread_start_fl(const char *file, int line, const char *thread_base_name) { struct tr2_tgt *tgt_j; int j; @@ -488,14 +488,14 @@ void trace2_thread_start_fl(const char *file, int line, const char *thread_name) */ trace2_region_enter_printf_fl(file, line, NULL, NULL, NULL, "thread-proc on main: %s", - thread_name); + thread_base_name); return; } us_now = getnanotime() / 1000; us_elapsed_absolute = tr2tls_absolute_elapsed(us_now); - tr2tls_create_self(thread_name, us_now); + tr2tls_create_self(thread_base_name, us_now); for_each_wanted_builtin (j, tgt_j) if (tgt_j->pfn_thread_start_fl) diff --git a/trace2.h b/trace2.h index af3c11694cc..74cdb1354f7 100644 --- a/trace2.h +++ b/trace2.h @@ -304,14 +304,15 @@ void trace2_exec_result_fl(const char *file, int line, int exec_id, int code); * thread-proc to allow the thread to create its own thread-local * storage. * - * Thread names should be descriptive, like "preload_index". - * Thread names will be decorated with an instance number automatically. + * The thread base name should be descriptive, like "preload_index" or + * taken from the thread-proc function. A unique thread name will be + * created from the given base name and the thread id automatically. */ void trace2_thread_start_fl(const char *file, int line, - const char *thread_name); + const char *thread_base_name); -#define trace2_thread_start(thread_name) \ - trace2_thread_start_fl(__FILE__, __LINE__, (thread_name)) +#define trace2_thread_start(thread_base_name) \ + trace2_thread_start_fl(__FILE__, __LINE__, (thread_base_name)) /* * Emit a 'thread_exit' event. This must be called from inside the diff --git a/trace2/tr2_tls.c b/trace2/tr2_tls.c index 8d2182fbdbb..4f7c516ecb6 100644 --- a/trace2/tr2_tls.c +++ b/trace2/tr2_tls.c @@ -31,7 +31,7 @@ void tr2tls_start_process_clock(void) tr2tls_us_start_process = getnanotime() / 1000; } -struct tr2tls_thread_ctx *tr2tls_create_self(const char *thread_name, +struct tr2tls_thread_ctx *tr2tls_create_self(const char *thread_base_name, uint64_t us_thread_start) { struct tr2tls_thread_ctx *ctx = xcalloc(1, sizeof(*ctx)); @@ -50,7 +50,7 @@ struct tr2tls_thread_ctx *tr2tls_create_self(const char *thread_name, strbuf_init(&ctx->thread_name, 0); if (ctx->thread_id) strbuf_addf(&ctx->thread_name, "th%02d:", ctx->thread_id); - strbuf_addstr(&ctx->thread_name, thread_name); + strbuf_addstr(&ctx->thread_name, thread_base_name); if (ctx->thread_name.len > TR2_MAX_THREAD_NAME) strbuf_setlen(&ctx->thread_name, TR2_MAX_THREAD_NAME); diff --git a/trace2/tr2_tls.h b/trace2/tr2_tls.h index 1297509fd23..7d1f03a2ea6 100644 --- a/trace2/tr2_tls.h +++ b/trace2/tr2_tls.h @@ -25,17 +25,20 @@ struct tr2tls_thread_ctx { /* * Create thread-local storage for the current thread. * - * We assume the first thread is "main". Other threads are given - * non-zero thread-ids to help distinguish messages from concurrent - * threads. - * - * Truncate the thread name if necessary to help with column alignment - * in printf-style messages. + * The first thread in the process will have: + * { .thread_id=0, .thread_name="main" } + * Subsequent threads are given a non-zero thread_id and a thread_name + * constructed from the id and a thread base name (which is usually just + * the name of the thread-proc function). For example: + * { .thread_id=10, .thread_name="th10fsm-listen" } + * This helps to identify and distinguish messages from concurrent threads. + * The ctx.thread_name field is truncated if necessary to help with column + * alignment in printf-style messages. * * In this and all following functions the term "self" refers to the * current thread. */ -struct tr2tls_thread_ctx *tr2tls_create_self(const char *thread_name, +struct tr2tls_thread_ctx *tr2tls_create_self(const char *thread_base_name, uint64_t us_thread_start); /* From patchwork Wed Oct 12 18:52:28 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jeff Hostetler X-Patchwork-Id: 13005374 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9D948C43217 for ; Wed, 12 Oct 2022 18:52:47 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229975AbiJLSwr (ORCPT ); Wed, 12 Oct 2022 14:52:47 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58416 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229716AbiJLSwl (ORCPT ); Wed, 12 Oct 2022 14:52:41 -0400 Received: from mail-wm1-x333.google.com (mail-wm1-x333.google.com [IPv6:2a00:1450:4864:20::333]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9CD5CF41AB for ; Wed, 12 Oct 2022 11:52:39 -0700 (PDT) Received: by mail-wm1-x333.google.com with SMTP id r3-20020a05600c35c300b003b4b5f6c6bdso1794964wmq.2 for ; Wed, 12 Oct 2022 11:52:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=49A0L1wMbmU0RvsqsmDPtIsptTiM40AWpEgBd9ZjT4Y=; b=KKeexWcNgUF568UqXPP+tTcB6yz6PpTYmaLfd37mffj18HSz6DiJ2ykK9AZGPi3g+q bBC8REXZq0W0if4Q34i+YrYyj+4pB4qMKcRYYY22X79EJbGasrivz2r/hxsj67VUeWEl bc61u3fKg5mz1vyDWVuYCWQD3alV/EIBut+Tq29rOr5vl0sryHSNvM3VnCvzVHfhtVOE vder7neB4w8QmVah/f/pBVIPcfeg6WdeVKf8+zoVuO/TqxatXluojF5mwNoo1Gq1XebS 2LrEu/JJPz0FKLHBDm+crWYZp0V0dLLteWOO7QypVhThUCQcP5YPhzBDMda+YwcgaS3S VrFQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=49A0L1wMbmU0RvsqsmDPtIsptTiM40AWpEgBd9ZjT4Y=; b=YBVGmVq7evxcEtqvpMD+qlTb61GhXPNOOsOSHUa+ER6bFWSW7rwRusclmMjqAfUYAV NHQLNl9hyA3Ay5cYf9PzlsqQ4wFfLd0my0yknN8ACoHrnfZJhVvsQuYaBwEFb6qwGhcI bsqhgHABQ4bWijO2yVkFRfOMSQv0PwDcQ5VKYS+7WcC1sLg6672XKRfLFg6MTuwkqJmm 6VQcmtTaHilFHrp3wwSohiMh3FDoUQ1dhndsdqmZb6pHvVFYc/+A/bD5uPdlC0fWf+ok FnnCNHbwVYNd1BWXtsUlGQWAOlcYFqo63xU+ATfbQDCoiMvOAIB5wJ+H6wFYVOAuDnQ2 cDHQ== X-Gm-Message-State: ACrzQf1+rnWeyEvQjCuWJYOvxqgQ0zsH5XPtK1vQgAs22TGx9yY51Xtf WcWAD6l0IoY6dREQ3wfq3QrazfYGIPY= X-Google-Smtp-Source: AMsMyM4pGa2Rwm/aTWa4H3Nc99AYuHDr/3FZFLqlW1zIPQDkf30cAdUrWDtmlg890vfNI6NWCtEFBA== X-Received: by 2002:a1c:3b41:0:b0:3bd:9167:c51e with SMTP id i62-20020a1c3b41000000b003bd9167c51emr3747563wma.102.1665600757446; Wed, 12 Oct 2022 11:52:37 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id k13-20020a05600c0b4d00b003bf3fe1d0c4sm2432310wmr.22.2022.10.12.11.52.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 12 Oct 2022 11:52:36 -0700 (PDT) Message-Id: <4bf78e356e23c947b8328a91ba435a357cd51f43.1665600750.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 12 Oct 2022 18:52:28 +0000 Subject: [PATCH v2 5/7] trace2: convert ctx.thread_name from strbuf to pointer Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsA==?= Bjarmason , Jeff Hostetler , Derrick Stolee , Jeff Hostetler , Jeff Hostetler Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Jeff Hostetler From: Jeff Hostetler Convert the `tr2tls_thread_ctx.thread_name` field from a `strbuf` to a "const char*" pointer. The `thread_name` field is a constant string that is constructed when the context is created. Using a (non-const) `strbuf` structure for it caused some confusion in the past because it implied that someone could rename a thread after it was created. That usage was not intended. Change it to a const pointer to make the intent more clear. Signed-off-by: Jeff Hostetler --- trace2/tr2_tgt_event.c | 2 +- trace2/tr2_tgt_perf.c | 2 +- trace2/tr2_tls.c | 16 +++++++++------- trace2/tr2_tls.h | 2 +- 4 files changed, 12 insertions(+), 10 deletions(-) diff --git a/trace2/tr2_tgt_event.c b/trace2/tr2_tgt_event.c index 37a3163be12..52f9356c695 100644 --- a/trace2/tr2_tgt_event.c +++ b/trace2/tr2_tgt_event.c @@ -90,7 +90,7 @@ static void event_fmt_prepare(const char *event_name, const char *file, jw_object_string(jw, "event", event_name); jw_object_string(jw, "sid", tr2_sid_get()); - jw_object_string(jw, "thread", ctx->thread_name.buf); + jw_object_string(jw, "thread", ctx->thread_name); /* * In brief mode, only emit