الفرق بين المراجعتين لصفحة: «Ruby/IO/read nonblock»

من موسوعة حسوب
< Ruby‏ | IO
→ التعديل السابق
مرئينص الويكي
لا ملخص تعديل
تدقيق
 
سطر 3: سطر 3:
[[تصنيف: Ruby Method]]
[[تصنيف: Ruby Method]]
[[تصنيف: Ruby IO]]
[[تصنيف: Ruby IO]]
يقرأ التابع <code>read_nonblock</code> على الأكثر <code>maxlen</code> (انظر فقرة البنية العامة) بايتًا من [[Ruby/IO|مجرى د/خ]] الذي استُدعي معه باستخدام استدعاء النظام <code>read(2)‎</code> بعد تعيين الراية <code>O_NONBLOCK</code> لواصف الملف (file descriptor) الأساسي.
يقرأ التابع <code>read_nonblock</code> عددًا محدَّدًا من البايتات من [[Ruby/IO|المجرى]] الذي استُدعي معه باستخدام استدعاء النظام <code>read(2)‎</code> بعد تعيين الراية <code>O_NONBLOCK</code> لواصف الملف (file descriptor) الأساسي.


في حال إعطاء الوسيط الاختياري <code>outbuf</code>، فينبغي أن يشير إلى [[Ruby/String|سلسلة نصية]]، والتي ستتلقى البيانات. لن يحتوي الوسيط <code>outbuf</code> إلا البيانات المستلمة بعد استدعاء التابع، حتى لو لم يكن فارغاً في البداية.
يستدعي التابع <code>read_nonblock</code> استدعاء النظام <code>read(2)‎</code>. كما أنه يتسبب في كل الأخطاء التي يسببها استدعاء النظام <code>read(2)‎</code>، مثل <code>Errno::EWOULDBLOCK</code> و <code>Errno::EINTR</code> وغيرهما . لذا، يجب على المُستدعي التعامل مع هذه الأخطاء.
 
يستدعي التابع <code>read_nonblock</code> استدعاء النظام <code>read(2)‎</code>. كما أنه يتسبب في كل الأخطاء التي يسببها استدعاء النظام <code>read(2)‎</code>، مثل <code>Errno::EWOULDBLOCK</code> و <code>Errno::EINTR</code> وغيرهما . لذا يجب على المُستدعي التعامل مع هذه الأخطاء.


إن كان الاستثناء هو أحد الاستثنائين <code>Errno::EWOULDBLOCK</code> أو <code>Errno::EAGAIN</code>، فسيتم توسيعه بواسطة التابع <code>[[Ruby/WaitReadable|WaitReadable]]</code>، حتى يمكن استخدامه  لمعالجة الاستثناءات لأجل إعادة استدعاء التابع <code>read_nonblock</code>.
إن كان الاستثناء هو أحد الاستثنائين <code>Errno::EWOULDBLOCK</code> أو <code>Errno::EAGAIN</code>، فسيتم توسيعه بواسطة التابع <code>[[Ruby/WaitReadable|WaitReadable]]</code>، حتى يمكن استخدامه  لمعالجة الاستثناءات لأجل إعادة استدعاء التابع <code>read_nonblock</code>.


يطلق التابع <code>read_nonblock</code> الخطأ <code>[[Ruby/EOFError|EOFError]]</code> عندما يصل إلى محرف نهايةالملف (<code>EOF</code>).
يطلق التابع <code>read_nonblock</code> الخطأ <code>[[Ruby/EOFError|EOFError]]</code> عندما يصل إلى محرف نهاية الملف (<code>EOF</code>).


إن كان المخزن المؤقت لقراءة البايت (read byte buffer) غير فارغ، فسيقرأ التابع <code>read_nonblock</code> من المخزن المؤقت كما يفعل التابع <code>[[Ruby/IO/readpartial|readpartial]]</code>. في هذه الحالة، لا يتم إجراء استدعاء النظام <code>read(2)‎</code>.
إن كان المخزن المؤقت لقراءة البايت (read byte buffer) غير فارغ، فسيقرأ التابع <code>read_nonblock</code> من المخزن المؤقت كما يفعل التابع <code>[[Ruby/IO/readpartial|readpartial]]</code>. في هذه الحالة، لا يتم استدعاء دالة النظام <code>read(2)‎</code>.


عندما يطلق التابع <code>read_nonblock</code> استثناءً من النوع <code>[[Ruby/WaitReadable|IO::WaitReadable]]</code>، فلا ينبغي استدعاء <code>read_nonblock</code> حتى يكون [[Ruby/IO|مجرى د/خ]] قابلاً للقراءة، لتجنب الحلقات التكرارية. يمكن القيام بذلك على النحو التالي.<syntaxhighlight lang="ruby"># emulates blocking read (readpartial).
عندما يطلق التابع <code>read_nonblock</code> استثناءً من النوع <code>[[Ruby/WaitReadable|IO::WaitReadable]]</code>، فلا ينبغي استدعاء <code>read_nonblock</code> حتى يكون [[Ruby/IO|المجرى]] قابلًا للقراءة لتجنب الحلقات التكرارية. يمكن القيام بذلك على النحو التالي:<syntaxhighlight lang="ruby"># (readpartial) محاكاة القراءة بالوضع المعطل
begin
begin
   result = io.read_nonblock(maxlen)
   result = io.read_nonblock(maxlen)
سطر 21: سطر 19:
   IO.select([io])
   IO.select([io])
   retry
   retry
end</syntaxhighlight>على الرغم من أن التابع <code>read_nonblock</code> لا يُطلق الاستثتاء <code>[[Ruby/WaitWritable|IO::WaitWritable]]</code>. فيمكن للتابع <code>OpenSSL::Buffering#read_nonblock</code> إطلاقه. إن كان من الضروري استخدام [[Ruby/IO|مجرى د/خ]]  و بروتوكول SSL بطريقة متعددة الأشكال (polymorphically)، فمن الضروري إذن أن يعالَج <code>[[Ruby/WaitWritable|IO::WaitWritable]]</code>. راجع توثيق <code>OpenSSL::Buffering#read_nonblock</code> للحصول على أمثلة.
end</syntaxhighlight>رغم أنَّ التابع <code>read_nonblock</code> لا يُطلق الاستثتاء <code>[[Ruby/WaitWritable|IO::WaitWritable]]</code>، فيمكن للتابع <code>OpenSSL::Buffering.read_nonblock</code> إطلاقه. إن كان من الضروري استخدام [[Ruby/IO|مجرى د/خ]]  و بروتوكول SSL بطريقة متعددة الأشكال (polymorphically)، فمن الضروري إذًا أن يعالَج <code>[[Ruby/WaitWritable|IO::WaitWritable]]</code>. راجع توثيق <code>OpenSSL::Buffering.read_nonblock</code> للاطلاع على مثلة بهذا الخصوص.
 
لاحظ أن هذا التابع مماثل للتابع [[Ruby/IO/readpartial|<code>readpartial</code>]]، باستثناء أن الراية non-blocking ستكون مٌعيّنة.


عبر إعطاء الوسيط المسمى (keyword argumen)‏ <code>exception</code>القيمة <code>false</code>، يمكنك منع التابع <code>read_nonblock</code> من إطلاق الاستثناء <code>[[Ruby/WaitReadable|IO::WaitReadable]]</code>، وجعله يُعيد [[Ruby/Symbol|الرمز]] ‎<code>:wait_readable</code> بدلاً من ذلك.
لاحظ أنَّ هذا التابع مماثل للتابع [[Ruby/IO/readpartial|<code>readpartial</code>]]، باستثناء أنَّ الراية <code>non-blocking</code> ستكون مٌعيّنة.


عند محرف نهاية الملف (<code>EOF</code>،) سيعيد التابع <code>read_nonblock</code> القيمة <code>nil</code> بدلاً من إطلاق <code>[[Ruby/EOFError|EOFError]]</code>.
عبر إعطاء الوسيط المسمى (keyword argumen)‏ <code>exception</code> القيمة <code>false</code>، يمكنك منع التابع <code>read_nonblock</code> من إطلاق الاستثناء <code>[[Ruby/WaitReadable|IO::WaitReadable]]</code>، وجعله يُعيد [[Ruby/Symbol|الرمز]] ‎<code>:wait_readable</code> بدلًا من ذلك.
==البنية العامة==
==البنية العامة==
<syntaxhighlight lang="ruby">read_nonblock(maxlen [, options])  → string
<syntaxhighlight lang="ruby">read_nonblock(maxlen [, options])  → string
سطر 33: سطر 29:
==المعاملات==
==المعاملات==
===<code>maxlen‎</code>===
===<code>maxlen‎</code>===
الحد الأقصى
[[Ruby/Integer|عدد صحيح]] يمثِّل الحد الأقصى للبايتات المراد قراءتها من المجرى المعطى.
===<code>outbuf‎</code>===
في حال إعطاء هذا المعامل الاختياري، فينبغي أن يشير إلى [[Ruby/String|السلسلة النصية]] التي ستتلقى البيانات المقروءة من المجرى. لن يحتوي <code>outbuf</code> إلا على البيانات المستلمة بعد استدعاء التابع حتى لو لم يكن فارغًا في البداية (أي ستُمسَح البيانات القديمة المخزنة فيه مسبقًا).
===<code>options‎</code>===
===<code>options‎</code>===
خيارات
خيارات تضبط عملية القراءة.
===<code>outbuf‎</code>===
==القيمة المعادة==
سلسلة نصية تتلقى البيانات
تعاد السلسلة النصية المقروءة من المجرى المعطى والتي لا يتجاوز حجمها الحجم <code>maxlen‎</code>. عند محرف نهاية الملف (<code>EOF</code>،) ستُعَاد القيمة <code>nil</code> بدلًا من إطلاق الاستثناء <code>[[Ruby/EOFError|EOFError]]</code>.
==القيمة المُعادة==
يعيد  التابع <code>read_nonblock</code> سلسلة نصية.


==انظر أيضا==
==انظر أيضًا==
*التابع <code>[[Ruby/IO/read-i|read]]</code>: يقرأ عددا من البايتات من [[Ruby/IO|مجرى د/خ]].
*التابع [[Ruby/IO/read-i|<code>read</code>]]: يقرأ عددًا محدَّدًا من البايتات من [[Ruby/IO|المجرى]] الذي استدعي معه.
*التابع <code>[[Ruby/IO/readbyte|readbyte]]</code>: يقرأ البايت كما يفعل التابع <code>IO#getbyte</code>، إلا أنه يُطلق الاستثناء <code>EOFError</code> عند نهاية الملف.
*التابع [[Ruby/IO/readbyte|<code>readbyte</code>]]: يقرأ بايتًا واحدًا من المجرى الذي استدعي معه.
*التابع [[Ruby/IO/readchar|<code>readchar</code>]]: يقرأ محرفًا واحدًا من [[Ruby/IO|المجرى]] الذي استدعي معه.
*التابع [[Ruby/IO/readline|<code>readline</code>]]: يقرأ سطرًا واحدًا من المجرى الذي استدعي معه.
*التابع [[Ruby/IO/readlines-i|<code>readlines</code>]]: يقرأ كل الأسطر الموجودة في [[Ruby/IO|المجرى]] الذي استدعي معه ثم يعيدها في [[Ruby/Array|مصفوفة]]. 
*التابع [[Ruby/IO/readpartial|<code>readpartial</code>]]: يقرأ عددًا محدَّدًا من البايتات من [[Ruby/IO|المجرى]] الذي استدعي معه.
==مصادر==
==مصادر==
*[http://ruby-doc.org/core-2.5.1/IO.html#method-i-read_nonblock قسم التابع read_nonblock‎ في الصنف IO‎ في توثيق روبي الرسمي.]
*[http://ruby-doc.org/core-2.5.1/IO.html#method-i-read_nonblock قسم التابع read_nonblock‎ في الصنف IO‎ في توثيق روبي الرسمي.]

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

يقرأ التابع read_nonblock عددًا محدَّدًا من البايتات من المجرى الذي استُدعي معه باستخدام استدعاء النظام read(2)‎ بعد تعيين الراية O_NONBLOCK لواصف الملف (file descriptor) الأساسي.

يستدعي التابع read_nonblock استدعاء النظام read(2)‎. كما أنه يتسبب في كل الأخطاء التي يسببها استدعاء النظام read(2)‎، مثل Errno::EWOULDBLOCK و Errno::EINTR وغيرهما . لذا، يجب على المُستدعي التعامل مع هذه الأخطاء.

إن كان الاستثناء هو أحد الاستثنائين Errno::EWOULDBLOCK أو Errno::EAGAIN، فسيتم توسيعه بواسطة التابع WaitReadable، حتى يمكن استخدامه لمعالجة الاستثناءات لأجل إعادة استدعاء التابع read_nonblock.

يطلق التابع read_nonblock الخطأ EOFError عندما يصل إلى محرف نهاية الملف (EOF).

إن كان المخزن المؤقت لقراءة البايت (read byte buffer) غير فارغ، فسيقرأ التابع read_nonblock من المخزن المؤقت كما يفعل التابع readpartial. في هذه الحالة، لا يتم استدعاء دالة النظام read(2)‎.

عندما يطلق التابع read_nonblock استثناءً من النوع IO::WaitReadable، فلا ينبغي استدعاء read_nonblock حتى يكون المجرى قابلًا للقراءة لتجنب الحلقات التكرارية. يمكن القيام بذلك على النحو التالي:

# (readpartial) محاكاة القراءة بالوضع المعطل
begin
  result = io.read_nonblock(maxlen)
rescue IO::WaitReadable
  IO.select([io])
  retry
end

رغم أنَّ التابع read_nonblock لا يُطلق الاستثتاء IO::WaitWritable، فيمكن للتابع OpenSSL::Buffering.read_nonblock إطلاقه. إن كان من الضروري استخدام مجرى د/خ و بروتوكول SSL بطريقة متعددة الأشكال (polymorphically)، فمن الضروري إذًا أن يعالَج IO::WaitWritable. راجع توثيق OpenSSL::Buffering.read_nonblock للاطلاع على مثلة بهذا الخصوص.

لاحظ أنَّ هذا التابع مماثل للتابع readpartial، باستثناء أنَّ الراية non-blocking ستكون مٌعيّنة.

عبر إعطاء الوسيط المسمى (keyword argumen)‏ exception القيمة false، يمكنك منع التابع read_nonblock من إطلاق الاستثناء IO::WaitReadable، وجعله يُعيد الرمز ‎:wait_readable بدلًا من ذلك.

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

read_nonblock(maxlen [, options])  → string
read_nonblock(maxlen, outbuf [, options])→ outbuf‎

المعاملات

maxlen‎

عدد صحيح يمثِّل الحد الأقصى للبايتات المراد قراءتها من المجرى المعطى.

outbuf‎

في حال إعطاء هذا المعامل الاختياري، فينبغي أن يشير إلى السلسلة النصية التي ستتلقى البيانات المقروءة من المجرى. لن يحتوي outbuf إلا على البيانات المستلمة بعد استدعاء التابع حتى لو لم يكن فارغًا في البداية (أي ستُمسَح البيانات القديمة المخزنة فيه مسبقًا).

options‎

خيارات تضبط عملية القراءة.

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

تعاد السلسلة النصية المقروءة من المجرى المعطى والتي لا يتجاوز حجمها الحجم maxlen‎. عند محرف نهاية الملف (EOF،) ستُعَاد القيمة nil بدلًا من إطلاق الاستثناء EOFError.

انظر أيضًا

  • التابع read: يقرأ عددًا محدَّدًا من البايتات من المجرى الذي استدعي معه.
  • التابع readbyte: يقرأ بايتًا واحدًا من المجرى الذي استدعي معه.
  • التابع readchar: يقرأ محرفًا واحدًا من المجرى الذي استدعي معه.
  • التابع readline: يقرأ سطرًا واحدًا من المجرى الذي استدعي معه.
  • التابع readlines: يقرأ كل الأسطر الموجودة في المجرى الذي استدعي معه ثم يعيدها في مصفوفة. 
  • التابع readpartial: يقرأ عددًا محدَّدًا من البايتات من المجرى الذي استدعي معه.

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Ruby/IO/read_nonblock&oldid=26613»