resource --- اطلاعات مصرف منابع

---

این ماژول سازوکارهای پایه‌ای را برای اندازه‌گیری و کنترل منابع سیستمی که توسط یک برنامه استفاده می‌شوند، فراهم می‌کند.

دسترس‌پذیری: Unix, not WASI.

ثابت‌های نمادین برای مشخص کردن منابع سیستمی خاص و درخواست اطلاعات استفاده درباره‌ی فرایند جاری یا فرزندان آن استفاده می‌شوند.

در صورت شکست فراخوانی سیستمی، استثنای OSError پرتاب می‌شود.

exception resource.error

یک نام مستعار منسوخ از OSError.

تغییر یافته در نسخه‌ی 3.3: پیرو PEP 3151، این کلاس به نام مستعار OSError تبدیل شد.

محدودیت‌های منابع

مصرف منابع می‌تواند با استفاده از تابع setrlimit() که در ادامه توضیح داده شده است، محدود شود. هر منبع با یک جفت حد کنترل می‌شود: یک حد نرم و یک حد سخت. حد نرم، حد فعلی است و ممکن است در طول زمان توسط یک فرایند کاهش یا افزایش یابد. حد نرم هرگز نمی‌تواند از حد سخت فراتر رود. حد سخت می‌تواند به هر مقداری که بزرگ‌تر از حد نرم باشد کاهش یابد، اما نمی‌تواند افزایش یابد. (تنها فرایندهایی که UID مؤثر ابرکاربر را دارند، می‌توانند یک حد سخت را افزایش دهند.)

منابع خاصی که می‌توانند محدود شوند، به سیستم وابسته‌اند. این منابع در صفحه راهنمای getrlimit(2) توضیح داده شده‌اند. منابع فهرست‌شده در زیر زمانی پشتیبانی می‌شوند که سیستم‌عامل زیربنایی از آن‌ها پشتیبانی کند؛ منابعی که سیستم‌عامل نمی‌تواند آن‌ها را بررسی یا کنترل کند، در این ماژول برای آن پلتفرم‌ها تعریف نشده‌اند.

resource.RLIM_INFINITY

ثابتی که برای نشان دادن محدودیت یک منبع نامحدود استفاده می‌شود.

resource.getrlimit(resource)

یک تاپل (soft, hard) شامل محدودیت‌های نرم و سخت فعلی برای resource برمی‌گرداند. اگر منبع نامعتبری تعیین شده باشد، ValueError پرتاب می‌کند، یا اگر فراخوانی سیستمی زیربنایی به‌طور غیرمنتظره‌ای شکست بخورد، error پرتاب می‌کند.

resource.setrlimit(resource, limits)

محدودیت‌های جدید مصرف resource را تنظیم می‌کند. آرگومان limits باید یک تاپل (soft, hard) شامل ۲ عدد صحیح باشد که محدودیت‌های جدید را توصیف می‌کند. می‌توان از مقدار RLIM_INFINITY برای درخواست محدودیتی نامحدود استفاده کرد.

اگر منبع نامعتبری مشخص شود، اگر محدودیت نرم جدید از محدودیت سخت فراتر رود، یا اگر فرایندی سعی کند محدودیت سخت خود را افزایش دهد، ValueError پرتاب می‌شود. مشخص کردن محدودیت با مقدار RLIM_INFINITY در حالی که محدودیت سخت یا محدودیت سیستم برای آن منبع نامحدود نباشد، باعث پرتاب ValueError می‌شود. فرایندی با UID مؤثر ابرکاربر می‌تواند هر مقدار معتبری برای محدودیت، از جمله نامحدود، درخواست کند، اما اگر محدودیت درخواستی از محدودیت اعمال‌شده از سوی سیستم فراتر رود، همچنان ValueError پرتاب می‌شود.

همچنین ممکن است setrlimit در صورت شکست خوردن فراخوانی سیستمی زیربنایی، error را پرتاب کند.

VxWorks فقط از تنظیم RLIMIT_NOFILE پشتیبانی می‌کند.

یک رویداد حسابرسی resource.setrlimit را با آرگومان‌های resource و limits پرتاب می‌کند.

resource.prlimit(pid, resource[, limits])

setrlimit() و getrlimit() را در یک تابع ترکیب می‌کند و امکان دریافت و تنظیم محدودیت‌های منابع یک فرایند دلخواه را فراهم می‌سازد. اگر pid برابر ۰ باشد، این فراخوانی به فرایند جاری اعمال می‌شود. resource و limits همان معنایی را دارند که در setrlimit() دارند، با این تفاوت که limits اختیاری است.

هنگامی که limits داده نشود، تابع محدودیت منبع فرایند pid را برمی‌گرداند. هنگامی که limits داده شود، محدودیت منبع فرایند تنظیم می‌شود و محدودیت منبع پیشین برگردانده می‌شود.

ProcessLookupError را هنگامی که pid یافت نشود و PermissionError را هنگامی که کاربر CAP_SYS_RESOURCE برای فرایند نداشته باشد، پرتاب می‌کند.

یک رویداد حسابرسی resource.prlimit را با آرگومان‌های pid، resource و limits پرتاب می‌کند.

دسترس‌پذیری: Linux >= 2.6.36 with glibc >= 2.13.

اضافه شده در نسخه‌ی 3.4.

این نمادها منابعی را تعریف می‌کنند که مصرف آن‌ها را می‌توان با استفاده از توابع setrlimit() و getrlimit() که در ادامه توضیح داده شده‌اند، کنترل کرد. مقادیر این نمادها دقیقاً همان ثابت‌هایی هستند که برنامه‌های C از آن‌ها استفاده می‌کنند.

صفحه راهنمای یونیکس برای getrlimit(2) منابع موجود را فهرست می‌کند. توجه داشته باشید که تمام سیستم‌ها از نماد یا مقدار یکسانی برای نشان دادن یک منبع یکسان استفاده نمی‌کنند. این ماژول تلاش نمی‌کند تفاوت‌های سکو را بپوشاند --- نمادهایی که برای یک سکو تعریف نشده‌اند، در آن سکو از این ماژول در دسترس نخواهند بود.

resource.RLIMIT_CORE

حداکثر اندازه‌ی پرونده core (بر حسب بایت) که فرایند جاری می‌تواند ایجاد کند. این موضوع ممکن است منجر به ایجاد یک پرونده core ناقص شود، در صورتی که برای دربرگرفتن کل تصویر فرایند به core بزرگ‌تری نیاز باشد.

resource.RLIMIT_CPU

حداکثر مقدار زمان پردازنده (بر حسب ثانیه) که یک فرایند می‌تواند از آن استفاده کند. در صورت عبور از این محدودیت، یک سیگنال SIGXCPU به فرایند ارسال می‌شود. (برای اطلاعات در مورد نحوه‌ی دریافت این سیگنال و انجام کاری مفید، مثلاً تخلیه‌ی پرونده‌های باز روی دیسک، مستندات ماژول signal را ببینید.)

resource.RLIMIT_FSIZE

حداکثر اندازه‌ی پرونده‌ای که فرایند می‌تواند ایجاد کند.

resource.RLIMIT_DATA

حداکثر اندازه‌ی انباشت فرایند (به بایت)

resource.RLIMIT_STACK

حداکثر اندازه‌ی پشته‌ی فراخوانی برای فرایند جاری (بر حسب بایت). این فقط بر پشته‌ی نخ اصلی در یک فرایند چندنخی تأثیر می‌گذارد.

resource.RLIMIT_RSS

حداکثر اندازه‌ی مجموعه مقیم (resident set size) که باید در دسترس فرایند قرار گیرد.

resource.RLIMIT_NPROC

حداکثر تعداد فرایندهایی که فرایند جاری می‌تواند ایجاد کند.

resource.RLIMIT_NOFILE

حداکثر تعداد توصیف‌گرهای پرونده باز برای فرایند جاری.

resource.RLIMIT_OFILE

نام BSD برای RLIMIT_NOFILE.

resource.RLIMIT_MEMLOCK

حداکثر فضای آدرسی که می‌تواند در حافظه قفل شود.

resource.RLIMIT_VMEM

بزرگ‌ترین ناحیه‌ی حافظه‌ی نگاشت‌شده که فرایند ممکن است اشغال کند. معمولاً نام مستعاری از RLIMIT_AS است.

دسترس‌پذیری: Solaris, FreeBSD, NetBSD.

resource.RLIMIT_AS

حداکثر ناحیه (به بایت) از فضای آدرس که ممکن است توسط فرایند اشغال شود.

resource.RLIMIT_MSGQUEUE

تعداد بایت‌هایی که می‌توان برای صف‌های پیام POSIX تخصیص داد.

دسترس‌پذیری: Linux >= 2.6.8.

اضافه شده در نسخه‌ی 3.4.

resource.RLIMIT_NICE

سقف سطح nice فرایند (که به‌صورت 20 - rlim_cur محاسبه می‌شود).

دسترس‌پذیری: Linux >= 2.6.12.

اضافه شده در نسخه‌ی 3.4.

resource.RLIMIT_RTPRIO

سقف اولویت بی‌درنگ.

دسترس‌پذیری: Linux >= 2.6.12.

اضافه شده در نسخه‌ی 3.4.

resource.RLIMIT_RTTIME

محدودیت زمانی (بر حسب میکروثانیه) برای زمان پردازنده‌ای که یک فرایند می‌تواند تحت زمان‌بندی بلادرنگ بدون انجام یک فراخوانی سیستمی مسدودکننده صرف کند.

دسترس‌پذیری: Linux >= 2.6.25.

اضافه شده در نسخه‌ی 3.4.

resource.RLIMIT_SIGPENDING

تعداد سیگنال‌هایی که فرایند می‌تواند در صف قرار دهد.

دسترس‌پذیری: Linux >= 2.6.8.

اضافه شده در نسخه‌ی 3.4.

resource.RLIMIT_SBSIZE

حداکثر اندازه‌ی مصرف بافر سوکت (به بایت) برای این کاربر. این میزان حافظه شبکه، و در نتیجه میزان mbufها (mbufs)، را که این کاربر ممکن است در هر زمان در اختیار داشته باشد محدود می‌کند.

دسترس‌پذیری: FreeBSD, NetBSD.

اضافه شده در نسخه‌ی 3.4.

resource.RLIMIT_SWAP

حداکثر اندازه (به بایت) فضای مبادله‌ای که ممکن است تمام فرآیندهای این شناسه کاربری آن را رزرو یا استفاده کنند. این محدودیت تنها در صورتی اعمال می‌شود که بیت ۱ از sysctlِ vm.overcommit تنظیم شده باشد. لطفاً برای توضیح کامل این sysctl، tuning(7) را ببینید.

دسترس‌پذیری: FreeBSD >= 8.

اضافه شده در نسخه‌ی 3.4.

resource.RLIMIT_NPTS

حداکثر تعداد شبه‌پایانه‌ها (pseudo-terminals) که توسط این شناسه کاربری ایجاد شده‌اند.

دسترس‌پذیری: FreeBSD >= 8.

اضافه شده در نسخه‌ی 3.4.

resource.RLIMIT_KQUEUES

حداکثر تعداد kqueueهایی که این شناسه کاربری مجاز به ایجاد آن‌ها است.

دسترس‌پذیری: FreeBSD >= 11.

اضافه شده در نسخه‌ی 3.10.

استفاده از منابع

این توابع برای بازیابی اطلاعات استفاده از منابع به کار می‌روند:

resource.getrusage(who)

این تابع شیءای را برمی‌گرداند که منابع مصرف‌شده توسط فرایند جاری یا فرایندهای فرزند آن را توصیف می‌کند، همان‌طور که با پارامتر who مشخص شده است. پارامتر who باید با استفاده از یکی از ثابت‌های RUSAGE_* که در ادامه توضیح داده شده‌اند، مشخص شود.

یک مثال ساده:

from resource import *
import time

# a non CPU-bound task
time.sleep(3)
print(getrusage(RUSAGE_SELF))

# a CPU-bound task
for i in range(10 ** 8):
   _ = 1 + 1
print(getrusage(RUSAGE_SELF))

هر یک از فیلدهای مقدار بازگشتی، نحوه استفاده از یک منبع سیستمی خاص را توصیف می‌کنند، برای مثال میزان زمانی که در حالت کاربر صرف اجرا شده یا تعداد دفعاتی که فرایند از حافظه اصلی خارجشده است. برخی مقادیر به بازه تیک ساعت وابسته‌اند، برای مثال میزان حافظه‌ای که فرایند در حال استفاده از آن است.

برای سازگاری با نسخه‌های پیشین، مقدار بازگشتی همچنین به‌صورت تاپلی از ۱۶ المان قابل دسترسی است.

فیلدهای ru_utime و ru_stime از مقدار بازگشتی، مقادیر ممیز شناور هستند که به‌ترتیب نشان‌دهنده‌ی میزان زمان صرف‌شده برای اجرا در حالت کاربر و میزان زمان صرف‌شده برای اجرا در حالت سیستم هستند. مقادیر باقی‌مانده، اعداد صحیح هستند. برای اطلاعات تفصیلی درباره‌ی این مقادیر به صفحه راهنمای getrusage(2) مراجعه کنید. خلاصه‌ای کوتاه در اینجا ارائه شده است:

اندیس	فیلد	منبع
0	ru_utime	زمان در حالت کاربر (ثانیه‌های شناور)
1	ru_stime	زمان در حالت سیستم (ثانیه به‌صورت float)
2	ru_maxrss	حداکثر اندازه مجموعه مقیم
3	ru_ixrss	اندازه‌ی حافظه‌ی مشترک
4	ru_idrss	اندازه‌ی حافظه‌ی غیرمشترک
5	ru_isrss	اندازه‌ی پشته‌ی اشتراک‌گذاری‌نشده
6	ru_minflt	خطاهای صفحه بدون نیاز به ورودی/خروجی
7	ru_majflt	خطاهای صفحه نیازمند I/O
8	ru_nswap	تعداد خروج‌های مبادله
9	ru_inblock	عملیات‌های ورودی بلوک
10	ru_oublock	عملیات‌های خروجی بلوک
11	ru_msgsnd	پیام‌های ارسال‌شده
12	ru_msgrcv	پیام‌های دریافتی
13	ru_nsignals	سیگنال‌های دریافت‌شده
14	ru_nvcsw	تعویض‌های زمینه داوطلبانه
15	ru_nivcsw	تعویض‌های غیرارادی زمینه

این تابع در صورت مشخص شدن یک پارامتر who نامعتبر، یک ValueError را پرتاب می‌کند. همچنین ممکن است در شرایط غیرمعمول، استثنای error را نیز پرتاب کند.

resource.getpagesize()

تعداد بایت‌های یک صفحه‌ی سیستم را برمی‌گرداند. (این مقدار لزوماً برابر با اندازه‌ی صفحه‌ی سخت‌افزاری نیست.)

نمادهای RUSAGE_* زیر به تابع getrusage() داده می‌شوند تا مشخص کنند اطلاعات کدام فرایندها باید ارائه شود.

resource.RUSAGE_SELF

آن را به getrusage() ارسال کنید تا منابع مصرف‌شده توسط فرایند فراخوان درخواست شود، که مجموع منابع استفاده‌شده توسط همه نخ‌های درون فرایند است.

resource.RUSAGE_CHILDREN

به getrusage() بفرستید تا منابع مصرف‌شده توسط فرایندهای فرزند فرایند فراخوان، که پایان‌یافته‌اند و انتظارشان کشیده شده است، درخواست شود.

resource.RUSAGE_BOTH

به getrusage() ارسال کنید تا منابع مصرف‌شده توسط فرآیند فعلی و فرآیندهای فرزند درخواست شود. ممکن است در همه‌ی سیستم‌ها در دسترس نباشد.

resource.RUSAGE_THREAD

برای درخواست منابع مصرف‌شده توسط نخ جاری، آن را به getrusage() بدهید. ممکن است در همه‌ی سیستم‌ها در دسترس نباشد.

اضافه شده در نسخه‌ی 3.2.