الفرق بين المراجعتين ل"Ruby/IO/advise"

المراجعة الحالية بتاريخ 08:23، 22 ديسمبر 2018

يعلن التابع advise عن نية الوصول إلى بيانات الملف الحالي وفق نمط محدد.

في أنظمة التشغيل التي لا تدعم استدعاء النظام posix_fadvise(2)‎، هذا التابع سيكون عمليةً فارغةً (no-op).

المقصود بـ "البيانات" هي الحيز من الملف الحالي الذي يبدأ عند الإزاحة offset (انظر قسم البينة العامة) ويمتد حتى len بايت. إن كان len يساوي 0، فسينتهي الحيّز عند البايت الأخير من الملف. افتراضيًّا، كلا الوسيطين offset و len يساويان 0، أي أن النصيحة تنطبق على الملف بأكمله.

في حالة حدوث خطأ، سيُطلَق أحد الاستثناءات التالية:

IOError: مجرى د/خ مغلق.
Errno::EBADF: واصف الملف (file descriptor) الحالي غير صالح.
Errno::EINVAL: تم إعطاء قيمة غير صالحة للوسيط advice.
Errno::ESPIPE: يشير واصف الملف الحالي إلى أنبوب (pipe) أو أنبوب مسمى (FIFO). (يطلق في لينكس الخطأ Errno::EINVAL في هذه الحالة).
TypeError: إما أنّ الوسيط advice ليس رمزًا، أو أنّ أحد الوسائط الأخرى ليس عددًا صحيحًا.
RangeError: أحد الوسائط المعطاة كبير جدًا، أو صغير جدًا.

هذه القائمة ليست شاملة لجميع الاستثناءات؛ فهناك أخطاء Errnoأخرى، كما أن الاستثناءات ممكنة أيضًا.

البنية العامة

advise(advice, offset=0, len=0) → nil‎

المعاملات

`advice‎`

يأخذ هذا المعامل أحد الرموز التالية:

normal: - لا نصيحة (advice) لتقديمها؛ ستُعتمَد الإعدادات الافتراضية للملفات المفتوحة.
‎:sequential - سيتم الوصول إلى البيانات بالتتابع، مع قراءة مواضع الإزاحة (offsets) الدنيا قبل العليا.

‎:random - سيتم الوصول إلى البيانات بترتيب عشوائي.
‎:willneed - سيتم الوصول إلى البيانات في المستقبل القريب.
‎:dontneed‎ - لن يتم الوصول إلى البيانات في المستقبل القريب.
‎:noreuse - لن يتم الوصول إلى البيانات إلا مرةً واحدةً فقط.

دلالات التوجيهات التي يقدمها المعامل advice تعتمد على النظام المُستخدَم. انظر صفحة الدليل man للدالة posix_fadvise لمزيد من التفاصيل.

`offset‎`

عدد صحيح يمثل الإزاحة. القيمة الافتراضية هي: 0.

`len‎`

عدد صحيح يمثل الطول الذي يشكل حيز البيانات. القيمة الافتراضية هي: 0.

القيمة المعادة

تعاد القيمة nil.

انظر أيضًا

التابع open: يشبه التابعَ new تمامًا عند استدعائه دون كتلة، أو يُمرّر الكائن IO الذي جرى إنشاؤه كوسيط إلى الكتلة المعطاة ثم يعيد الناتج الذي تعيده الكتلة.

مصادر

قسم التابع advise‎ في الصنف IO‎ في توثيق روبي الرسمي.

@@ سطر 3: / سطر 3: @@
 [[تصنيف: Ruby Method]]
 [[تصنيف: Ruby IO]]
-يعلن التابع <code>advise</code> عن نية الوصول إلى البيانات من الملف الحالي وفق نمط محدد. على أنظمة التشغيل التي لا تدعم استدعاء النظام <code>posix_fadvise(2)</code>، هذه التابع عبارة عن عملية فارغة (no-op).
+يعلن التابع <code>advise</code> عن نية الوصول إلى بيانات الملف الحالي وفق نمط محدد.
-الوسيط <code>advice</code> سيكون أحد الرموز التالية:
+في أنظمة التشغيل التي لا تدعم استدعاء النظام <code>posix_fadvise(2)‎</code>، هذا التابع سيكون عمليةً فارغةً (no-op).
-:normal
+المقصود بـ "البيانات" هي الحيز من الملف الحالي الذي يبدأ عند الإزاحة <code>offset</code> (انظر قسم البينة العامة) ويمتد حتى <code>len</code> بايت. إن كان <code>len</code> يساوي <code>0</code>، فسينتهي الحيّز عند البايت الأخير من الملف. افتراضيًّا، كلا الوسيطين <code>offset</code> و <code>len</code> يساويان <code>0</code>، أي أن النصيحة تنطبق على الملف بأكمله.
-لا نصيحة لتقديمها؛ الإعدادات الافتراضية لملف مفتوح.
+في حالة حدوث خطأ، سيُطلَق أحد الاستثناءات التالية:
+* <code>[[Ruby/IOError|IOError]]</code>: [[Ruby/IO|مجرى د/خ]] مغلق.
-‎:sequential
+* <code>Errno::EBADF</code>: واصف الملف (file descriptor) الحالي غير صالح.
+* <code>Errno::EINVAL</code>: تم إعطاء قيمة غير صالحة للوسيط <code>advice</code>.
-سيتم الدخول إلى البيانات بالتتابع، مع قراءة مواضع الإزاحة (offsets) الدنياا قبل العليا.
+* <code>Errno::ESPIPE</code>: يشير واصف الملف الحالي إلى أنبوب (pipe) أو أنبوب مسمى (FIFO). (يطلق في لينكس الخطأ <code>Errno::EINVAL</code> في هذه الحالة).
+* <code>[[Ruby/TypeError|TypeError]]</code>: إما أنّ الوسيط <code>advice</code> ليس [[Ruby/Symbol|رمزً]]ا، أو أنّ أحد الوسائط الأخرى ليس [[Ruby/Integer|عددًا صحيحً]]ا.
-‎:random ‎
+* <code>[[Ruby/RangeError|RangeError]]</code>: أحد الوسائط المعطاة كبير جدًا، أو صغير جدًا.
+هذه القائمة ليست شاملة لجميع الاستثناءات؛ فهناك أخطاء <code>[[Ruby/Errno|Errno]]</code>أخرى، كما أن الاستثناءات ممكنة أيضًا.
-سيتم الدخول إلى البيانات بترتيب عشوائي.
-‎:willneed
-سيتم الدخول إلى البيانات في المستقبل القريب.
-‎:dontneed‎
-لن يتم الدخول إلى البيانات في المستقبل القريب.
-‎:noreuse
-لن يتم الدخول إلى البيانات إلا مرة واحدة فقط.
-دلالات التوجيهات التي يقدمها الوسيط advice تعتمد على النظام المُستخدم. انظر صفحة <code>man 2
-posix_fadvise</code> لمزيد من التفاصيل.
-المقصود ب"البيانات" الحيز من الملف الحالي الذي يبدأ عند <code>offset</code> ويمتد لـ <code>len</code> بايت. إن كان <code>len</code> يساوي 0، فسينتهي الحيّز عند البايت الأخير من الملف. افتراضيا، كلا الوسيطين <code>offset</code> و <code>len</code> يساويان 0، أي أن النصيحة تنطبق على الملف بأكمله.
-في حالة حدوث خطأ، سيُطلق أحد الاستثناءات التالية:
-<code>IOError</code>
-[[Ruby/IO|مجرى د/خ]] <code>IO</code> مغلق.
-<code>Errno::EBADF</code>
-واصف الملف الخاص بالملف الحالي غير صالح.
-<code>Errno::EINVAL</code>
-تم إعطاء قيمة غير صالحة للوسيط <code>advice</code>.
-<code>Errno::ESPIPE</code>
-يشير واصف الملف الخاص بالملف الحالي إلى أنبوب أو أنبوب مسمى (FIFO). (يطلق اللينكس الخطأ <code>Errno::EINVAL</code> في هذه الحالة).
-<code>TypeError</code>
-إما أنّ الوسيط <code>advice</code> ليس [[Ruby/Symbol|رمز]]ا <code>[[Ruby/Symbol|Symbol]]</code>، أو أنّ أحد الوسائط الأخرى ليس [[Ruby/Integer|عدد صحيح]]ا <code>[[Ruby/Integer|Integer]]</code>.
-<code>RangeError</code>
-أحد من الوسائط المعطاة كبير جدا، أو صغير جدا.
-هذه القائمة ليست شاملة؛ أخطاء أخرى <code>[[Ruby/Errno|Errno]]</code>
-الاستثناءات ممكنة أيضا.
 ==البنية العامة==
 <syntaxhighlight lang="ruby">advise(advice, offset=0, len=0) → nil‎</syntaxhighlight>
 ==المعاملات==
 ===<code>advice‎</code>===
+يأخذ هذا المعامل أحد الرموز التالية:
+* <code>normal:</code> - لا نصيحة (advice) لتقديمها؛ ستُعتمَد الإعدادات الافتراضية للملفات المفتوحة.
+* <code>‎:sequential</code> - سيتم الوصول إلى البيانات بالتتابع، مع قراءة مواضع الإزاحة (offsets) الدنيا قبل العليا.
+* <code>‎:random</code> - سيتم الوصول إلى البيانات بترتيب عشوائي.
+* <code>‎:willneed</code> - سيتم الوصول إلى البيانات في المستقبل القريب.
+* ‎<code>:dontneed‎</code> - لن يتم الوصول إلى البيانات في المستقبل القريب.
+* <code>‎:noreuse</code> - لن يتم الوصول إلى البيانات إلا مرةً واحدةً فقط.
+دلالات التوجيهات التي يقدمها المعامل <code>advice</code> تعتمد على النظام المُستخدَم. انظر صفحة الدليل man للدالة <code>posix_fadvise</code> لمزيد من التفاصيل.
 ===<code>offset‎</code>===
-عدد صحيح يمثل الإزاحة
+عدد صحيح يمثل الإزاحة. القيمة الافتراضية هي: 0.
 ===<code>len‎</code>===
-==القيمة المُعادة==
+عدد صحيح يمثل الطول الذي يشكل حيز البيانات. القيمة الافتراضية هي: 0.
-==انظر أيضا==
-* التابع <code>[[Ruby/IO/left_shift|<<]]</code>: مجرى الإخراج النصي <code>[[Ruby/String|String]]</code> - يكتب <code>obj</code> (انظر فقرة البنية العامة) في المجرى <code>ios</code>. سيتم تحويل <code>obj</code> إلى [[Ruby/String|سلسلة نصية]] باستخدام <code>to_s</code>.
+==القيمة المعادة==
-* التابع <code>[[Ruby/IO/autoclose-3D|autoclose=]]</code>: يُعيّن  قيمة راية الإغلاق التلقائي.
+تعاد القيمة <code>nil</code>.
+==انظر أيضًا==
+*التابع [[Ruby/IO/open|<code>open</code>]]: يشبه التابعَ <code>[[Ruby/IO/new|new]]</code> تمامًا عند استدعائه دون كتلة، أو يُمرّر الكائن <code>IO</code> الذي جرى إنشاؤه كوسيط إلى الكتلة المعطاة ثم يعيد الناتج الذي تعيده الكتلة.
 ==مصادر==
-*[http://ruby-doc.org/core-2.5.1/IO.html#method-i-advise قسم  التابع advise‎ في الصنف IO‎ في توثيق روبي الرسمي.]
+*[http://ruby-doc.org/core-2.5.1/IO.html#method-i-advise قسم التابع advise‎ في الصنف IO‎ في توثيق روبي الرسمي.]