.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "RRDTHREADS 1"
.TH RRDTHREADS 1 2026-08-08 1.11.0 rrdtool
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "نام (NAME)"
rrdthreads \- تمهیدات پیوند دادن کتابخانه RRD جهت استفاده در برنامه‌های چندنخی
.SH "خلاصه دستور (SYNOPSIS)"
.IX Header "SYNOPSIS"
استفاده از \fIlibrrd\fR در برنامه‌های چندنخی (multi\-threaded) نیازمند برخی احتیاط‌های بیشتر است. این سند الزامات و دام‌های موجود در مسیر استفاده از \fIlibrrd\fR در برنامه‌هایتان را تشریح می‌کند. همچنین نکاتی را برای توسعهٔ آیندهٔ RRD جهت امن نگه‌داشتن کتابخانه در برابر نخ‌ها (thread\-safe) ارائه می‌دهد.
.PP
از زمان RRDtool 1.6، کتابخانهٔ \fIlibrrd\fR امن در برابر نخ (thread\-safe) است و نیازی به کتابخانهٔ جداگانهٔ مخصوص نخ نیست.
.SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
جهت استفاده از \fIlibrrd\fR در برنامه‌های چندنخی باید موارد زیر را رعایت کنید:
.IP \(bu 4
پیوند با \fIlibrrd\fR (هنگام پیوند دادن از \f(CW\*(C`\-lrrd\*(C'\fR استفاده کنید)
.IP \(bu 4
استفاده از توابع «\f(CW\*(C`_r\*(C'\fR» به جای توابع عادی API
.IP \(bu 4
از هیچ‌گونه مشخصه زمانی به سبک at استفاده نکنید. تجزیهٔ چنین مشخصه‌های زمانی به هیچ وجه thread\-safe نیست.
.IP \(bu 4
هرگز از توابع غیر *\f(CW\*(C`_r\*(C'\fR استفاده نکنید مگر اینکه در مستندات صراحتاً قید شده باشد که آن تابع thread\-safe است.
.IP \(bu 4
هر نخ باید پیش از نخستین فراخوانی هر تابع \f(CW\*(C`librrd\*(C'\fR، تابع \f(CWrrd_get_context()\fR را جهت راه‌اندازی داده‌های مختص نخ فراخوانی کند. این کار کاملاً الزامی نیست، اما تنها راه برای آزمایش این است که آیا تخصیص حافظه توسط این تابع امکان‌پذیر است یا خیر. در غیر این صورت ممکن است برنامه در شرایط کمبود حافظه با یک SIGSEGV متوقف شود.
.IP \(bu 4
همیشه پیش از هر فراخوانی از کتابخانه، \f(CWrrd_clear_error()\fR را فراخوانی کنید. در غیر این صورت ممکن است فراخوانی به دلیل خطای قبلی با شکست مواجه شود.
.SS "نکاتی برای مشارکت‌کنندگان RRD (NOTES FOR RRD CONTRIBUTORS)"
.IX Subsection "NOTES FOR RRD CONTRIBUTORS"
از این پس در هنگام توسعهٔ RRD باید برخی موارد احتیاطی رعایت شود:
.IP \(bu 4
تنها از توابع thread\-safe در کد کتابخانه استفاده کنید. بسیاری از توابع پرکاربرد libc امن در برابر نخ نیستند. در شرایط زیر یا هنگام استفاده از توابع کتابخانه‌ای زیر دقت فرمایید:
.RS 4
.IP \(bu 4
باید از فراخوانی مستقیم \f(CWstrerror()\fR خودداری شود: به جای آن از \f(CWrrd_strerror()\fR استفاده کنید که یک پیام خطای اختصاصی برای هر نخ ارائه می‌دهد.
.IP \(bu 4
خانواده‌های توابع \f(CW\*(C`getpw*\*(C'\fR، \f(CW\*(C`getgr*\*(C'\fR، \f(CW\*(C`gethost*\*(C'\fR (و چند تابع \f(CW\*(C`get*\*(C'\fR دیگر) امن در برابر نخ نیستند: از گونه‌های *\f(CW\*(C`_r\*(C'\fR استفاده کنید
.IP \(bu 4
توابع زمان: \f(CW\*(C`asctime\*(C'\fR، \f(CW\*(C`ctime\*(C'\fR، \f(CW\*(C`gmtime\*(C'\fR، \f(CW\*(C`localtime\*(C'\fR: از گونه‌های *\f(CW\*(C`_r\*(C'\fR استفاده کنید
.IP \(bu 4
\&\f(CW\*(C`strtok\*(C'\fR: از \f(CW\*(C`strtok_r\*(C'\fR استفاده کنید
.IP \(bu 4
\&\f(CW\*(C`tmpnam\*(C'\fR: از \f(CW\*(C`tmpnam_r\*(C'\fR استفاده کنید
.IP \(bu 4
بسیاری موارد دیگر (مستندات را بررسی کنید)
.RE
.RS 4
.RE
.IP \(bu 4
یک فایل سرآیند به نام \fIrrd_is_thread_safe.h\fR ارائه شده است که با پیش‌پردازندهٔ GNU C کار می‌کند تا برخی از رایج‌ترین توابع غیر thread\-safe را با استفاده از دستورالعمل \f(CW\*(C`#pragma GCC poison\*(C'\fR اصطلاحاً «مسموم» (poison) کند. کافی است این سرآیند را در فایل‌های مبدایی که می‌خواهید thread\-safe بمانند، بگنجانید.
.IP \(bu 4
متغیرهای سراسری تعریف نکنید!
.Sp
اگر واقعاً، واقعاً مجبور به استفاده از یک متغیر سراسری هستید، می‌توانید یک فیلد جدید به ساختار \f(CW\*(C`rrd_context\*(C'\fR بیفزایید و فایل‌های \fIrrd_error.c\fR، \&\fIrrd_thread_safe.c\fR و \fIrrd_non_thread_safe.c\fR را تغییر دهید.
.IP \(bu 4
در *\f(CW\*(C`_r\*(C'\fR از \f(CW\*(C`getopt\*(C'\fR یا \f(CW\*(C`getopt_long\*(C'\fR (نه به صورت مستقیم و نه غیرمستقیم) استفاده نکنید.
.Sp
تابع \f(CW\*(C`getopt\*(C'\fR از متغیرهای سراسری استفاده می‌کند و هنگام فراخوانی هم‌روند در یک برنامهٔ چندنخی، رفتار نادرستی از خود نشان می‌دهد. در عوض، یک تابع *_r ارائه دهید که تمام گزینه‌ها را به عنوان پارامترهای تابع دریافت کند. می‌توانید آرگومان‌های argc و **argv را برای فهرست‌های آرگومان با طول متغیر در نظر بگیرید. به عنوان نمونه به \f(CW\*(C`rrd_update_r\*(C'\fR نگاه کنید.
.IP \(bu 4
از تابع \f(CW\*(C`rrd_parsetime\*(C'\fR استفاده نکنید!
.Sp
این تابع از متغیرهای سراسری متعددی استفاده می‌کند. می‌توانید از آن در توابعی که برای thread\-safe بودن طراحی نشده‌اند استفاده کنید، مانند توابعی که نسخهٔ \f(CW\*(C`_r\*(C'\fR یک عملیات را دربرمی‌گیرند (مانند \f(CW\*(C`rrd_create\*(C'\fR، اما نه در \f(CW\*(C`rrd_create_r\*(C'\fR).
.SS "توابع امن در برابر نخ پیاده‌سازی‌شده در حال حاضر (CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS)"
.IX Subsection "CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS"
در حال حاضر گونه‌های thread\-safe از \f(CW\*(C`rrd_update\*(C'\fR، \&\f(CW\*(C`rrd_create\*(C'\fR، \f(CW\*(C`rrd_dump\*(C'\fR، \f(CW\*(C`rrd_info\*(C'\fR، \f(CW\*(C`rrd_last\*(C'\fR و \f(CW\*(C`rrd_fetch\*(C'\fR وجود دارند.
.SH "نویسندگان (AUTHORS)"
.IX Header "AUTHOR"
Peter Stamfest <peter@stamfest.at>