Node.js/v8

تعرض الوحدة v8 واجهات برمجة التطبيقات (API) الخاصة بإصدار V8 المضمنة في برمجية Node.js. ويمكن الوصول إليها باستخدام:

const v8 = require('v8');

وقد يتعرض كلٌ من واجهات برمجة التطبيقات والتنفيذ للتغيير في أي وقت.

v8.cachedDataVersionTag()‎

أُضيف مع الإصدار: v8.0.0.

    • القيمة المُعادة: من النوع <integer>.

يُعيد عدد صحيح يمثل "وسم الإصدار" مشتق من الإصدار V8، ورايات سطر الأوامر وميزات المعالج CPU المكتشفة. وهو يفيد في تحديد ما إذا كان المخزن المؤقت لـ cacheddata الخاص بـ vm.Script متوافق مع مثيل V8 هذا.

v8.getHeapSpaceStatistics()‎ [المصدر]

سجل التغييرات

الإصدار	التغييرات
v7.5.0	دعم القيم التي تتجاوز نطاق الأعداد الصحيح بدون إشارة 32 بت.
v6.0.0	أُضيف مع الإصدار: v6.0.0.

    • القيمة المُعادة: من النوع <Object[]‎>.

يُعيد إحصائيات حول مساحات تكدس V8، أي المقاطع التي تشكل تكدس V8. لا يمكن ضمان ترتيب مساحات تكدس، ولا توفرها إذ تتغير الإحصاءات المُعادة من دالة v8.getHeapSpaceStatistics من أحد إصدارات V8 إلى الإصدار التالي.

القيمة المُعادة هي مصفوفة من الكائنات التي تحتوي على الخصائص التالية:

    • space_name من النوع <string>.

    • space_size من النوع <number>.

    • space_used_size من النوع <number>.

    • space_available_size  من النوع <number>.

    • physical_space_size من النوع <number>.

[
  {
    "space_name": "new_space",
    "space_size": 2063872,
    "space_used_size": 951112,
    "space_available_size": 80824,
    "physical_space_size": 2063872
  },
  {
    "space_name": "old_space",
    "space_size": 3090560,
    "space_used_size": 2493792,
    "space_available_size": 0,
    "physical_space_size": 3090560
  },
  {
    "space_name": "code_space",
    "space_size": 1260160,
    "space_used_size": 644256,
    "space_available_size": 960,
    "physical_space_size": 1260160
  },
  {
    "space_name": "map_space",
    "space_size": 1094160,
    "space_used_size": 201608,
    "space_available_size": 0,
    "physical_space_size": 1094160
  },
  {
    "space_name": "large_object_space",
    "space_size": 0,
    "space_used_size": 0,
    "space_available_size": 1490980608,
    "physical_space_size": 0
  }
]

v8.getHeapStatistics()‎ [المصدر]

سجل التغييرات

الإصدار	التغييرات
v7.5.0	دعم القيم التي تتجاوز نطاق الأعداد الصحيح بدون إشارة 32 بت.
v7.2.0	إضافة  malloced_memory و  peak_malloced_memory و does_zap_garbage.
v1.0.0	أُضيف مع الإصدار: v1.0.0

    • القيمة المُعادة: من النوع <Object>.

يُعيد كائن بالخصائص التالية:

    • total_heap_size من النوع <number>.

    • total_heap_size_executable من النوع <number>.

    • total_physical_size من النوع <number>.

    • total_available_size من النوع <number>.

    • used_heap_size من النوع <number>.

    • heap_size_limit من النوع <number>.

    • malloced_memory من النوع <number>.

    • peak_malloced_memory من النوع <number>.

    • does_zap_garbage من النوع <number>.

does_zap_garbage من النوع Boolean بقيمة 0/1، والذي يدل علي ما إذا كان الخيار ‎--zap_code_space مُفعَِّل أم لا. وهذا يجعل V8 يعيد الكتابة فوق المهملات المكدسة بنمط بت. تتضخم بصمة RSS (مجموعة الذاكرة المُقِيمة) لأنها تمس باستمرار جميع صفحات المكدس والتي تجعلها اقل عرضة للمبادلة من قِبَل نظام التشغيل.

{
  total_heap_size: 7326976,
  total_heap_size_executable: 4194304,
  total_physical_size: 7326976,
  total_available_size: 1152656,
  used_heap_size: 3476208,
  heap_size_limit: 1535115264,
  malloced_memory: 16384,
  peak_malloced_memory: 1127496,
  does_zap_garbage: 0
}

v8.setFlagsFromString(flags)‎ [المصدر]

أضيف مع الإصدار: v1.0.0.

    • flags من النوع <string>.

يمكن استخدام التابع v8.setFlagsFromString()‎ لتعيين رايات سطر الأوامر V8 برمجيًا. وينبغي استخدام هذا التابع بحرص. فقد يؤدي تغيير الإعدادات بعد بدء VM إلى سلوك غير متوقع، بما في ذلك الأعطال وفقدان البيانات؛ أو قد لا تفعل شيئًا ببساطة.

قد تُحدد خيارات v8 المتوفرة لإصدار Node.js عن طريق تشغيل node --v8-options. وتوجد هنا قائمة غير رسمية من الخيارات وتأثيرها مُصانة من مجتمع البرمجة.

الاستخدام:

// طباعة أحداث GC على stdout لمدة دقيقة واحدة.
const v8 = require('v8');
v8.setFlagsFromString('--trace_gc');
setTimeout(function() { v8.setFlagsFromString('--notrace_gc'); }, 60e3);

واجهة تطبيقات التسلسل (Serialization API)

مؤشر الاستقرار: 1 - تجريبي

توفر واجهة تطبيقات التسلسل وسيلة لتسلسل قيم JavaScript بطريقة متوافقة مع خوارزمية استنساخ HTML الهيكلية. ويتوافق التنسيق مع الإصدارات السابقة (أي آمن لتخزينه علي القرص).

لا تزال هذه الـ API قيد التطوير، والتغييرات قد تحدث حتى إزالة هذا التحذير (بما في ذلك التغييرات غير المتوافقة مع API أو تنسيق الأسلاك).

v8.serialize(value)‎ [المصدر]

أُضيف مع الإصدار: v8.0.0.

    • value من أي نوع من الأنواع <any>.

    • القيمة المُعادة: من النوع <Buffer>.

يستخدم DefaultSerializer في تسلسل القيمة value إلى داخل المخزن المؤقت.

v8.deserialize(buffer)‎ [المصدر]

أُضيف مع الإصدار: v8.0.0.

    • buffer من النوع ‎<Buffer> | <Uint8Array>‎وهو مخزن مؤقت يُعاد من قِبَل serialize()‎.

يستخدم DefaultDeserializer مع الخيارات الافتراضية لقراءة قيمة JS من المخزن المؤقت.

الصنف: v8.Serializer

أُضيف مع الإصدار: v8.0.0.

Serializer()‎ الجديد

إنشاء كائن serializer جديد.

serializer.writeHeader()‎

يُكوِّن الترويسة ويكتبها، والتي تتضمن إصدار تنسيق التسلسل.

serializer.writeValue(value)‎

    • value من أي نوع من الأنواع <any>.

يُسلسل قيمة JavaScript ويضيف التمثيل المتسلسل إلى المخزن المؤقت الداخلي.

ويُطلق خطأ إذا لم يتمكن من إجراء تسلسل القيمة value.

serializer.releaseBuffer()‎

    • القيمة المُعادة: من النوع <Buffer>.

يُعيد المخزن المؤقت الداخلي المخزون. لا يجب استخدام هذا المُسلسِل إذا حدث تفريغ للمخزن المؤقت. استدعاء هذا التابع يؤدي إلى سلوك غير مُعرَّف إذا فشلت عملية الكتابة السابقة.

serializer.transferArrayBuffer(id, arrayBuffer)‎

    • id من النوع <integer> وهو عدد صحيح 32 بت بدون إشارة.

    • arrayBuffer من النوع <ArrayBuffer> وهو مثيل لـ ArrayBuffer.

يشير إلى ArrayBuffer كما لو كانت محتوياته قد نُقلت خارج النطاق. ويمرر ArrayBuffer المقابل في سياق إلغاء التسلسل إلى التابع deserializer.transferArrayBuffer()‎.

serializer.writeUint32(value)‎

    • value من النوع<integer>.

كتابة عدد صحيح 32 بت خام بدون إشارة. للاستخدام داخل التابع serializer._writeHostObject()‎ المخصص.

serializer.writeUint64(hi, lo)‎

    • hi  من النوع <integer>.

    • lo من النوع <integer>.

كتابة عدد صحيح 64 بت خام بدون إشارة، مقسمة إلى جزأين؛ علوي وسفلي كل منهما 32 بت. للاستخدام داخل التابع serializer._writeHostObject()‎ المخصص.

serializer.writeDouble(value)‎

    • value من النوع <number>.

كتابة قيمة من النوع number. للاستخدام داخل التابع serializer._writeHostObject()‎ المخصص.

serializer.writeRawBytes(buffer)‎

    buffer من النوع ‎<Buffer> | <Uint8Array>‎كتابه وحدات البايت الخام في المخزن المؤقت الداخلي للمُسلسِل. سيتطلب إلغاء التسلسل طريقة لحساب طول المخزن المؤقت. للاستخدام داخل التابع serializer._writeHostObject()‎ المخصص.

serializer._writeHostObject(object)‎

    • object من النوع <Object>.

ويُستدعى هذا التابع لكتابة نوع من الكائنات المضيفة، أي كائن مُنشأ بواسطة روابط C++‎ الأصلي. إذا لم يكن من الممكن إجراء تسلسل object، يجب إجراء استثناء مناسب.

هذا التابع غير موجود ضمن الصنف Serializer نفسه ولكن يمكن توفيره بواسطة الأصناف الفرعية.

serializer._getDataCloneError(message)‎

    • message من النوع <string>.

يستدعى هذا التابع لإنشاء كائنات الأخطاء التي ستنطلق عندما لا يمكن استنساخ كائن.

يعيد هذا التابع قيمة افتراضية إلى مُنشئ الخطأ Error ويمكن تجاوزه في الأصناف الفرعية.

serializer._getSharedArrayBufferId(sharedArrayBuffer)‎

    • sharedArrayBuffer من النوع <SharedArrayBuffer>.

يُستدعى هذا التابع عند إجراء المُسلسِل عملية تسلسل لكائن SharedArrayBuffer. يجب أن يعيد مُعرِّف ID من النوع عدد صحيح بدون إشارة 32 بت للكائن، وذلك باستخدام نفس المعرف إذا كان قد سبق إجراء تسلسل للوسيط SharedArrayBuffer. عند إلغاء التسلسل، سيمرر هذا المعرف إلى deserializer.transferArrayBuffer()‎.

إذا تعذر إجراء تسلسل الكائن، يجب عمل استثناء.

هذا التابع غير موجود ضمن الصنف Serializer نفسه ولكن يمكن توفيره بواسطة الأصناف الفرعية.

serializer._setTreatArrayBufferViewsAsHostObjects(flag)‎

    • flag من النوع <boolean>. القيمة الافتراضية: false.

يحدد ما إذا كان سيُتعامل مع كائنات TypedArray و DataView ككائنات مضيفة، أي تمريرها إلى التابع serializer._writeHostObject()‎.

الصنف: v8.Deserializer

أُضيف مع الإصدار: v8.0.0.

Deserializer(buffer)‎ الجديد

    • buffer من النوع ‎<Buffer> | <Uint8Array>‎وهو مخزن مؤقت يُعاد من قِبَل serializer.releaseBuffer()‎.

إنشاء كائن Deserializer جديد.

deserializer.readHeader()‎

يقرأ ويتحقق من الترويسة (بما في ذلك تنسيق الإصدار). على سبيل المثال، قد يرفض تنسيق أسلاك غير صالح أو غير مدعوم. في هذه الحالة، سينطلق Error.

deserializer.readValue()‎

إلغاء تسلسل قيمة JavaScript من المخزن المؤقت وإعادته.

deserializer.transferArrayBuffer(id, arrayBuffer)‎

    • id من النوع <integer> وهو عدد صحيح 32 بت بدون إشارة.

    • arrayBuffer من النوع ‎<ArrayBuffer> | <SharedArrayBuffer>‎ وهي مثيل لـ ArrayBuffer.

يشير إلى ArrayBuffer كما لو كانت محتوياته قد نُقلت خارج النطاق. تمرير arraybuffer المقابل في سياق التسلسل للتابع serializer.transferArrayBuffer()‎ (أو إعادة المعرف id من التابع serializer._getSharedArrayBufferId()‎ في حالات SharedArrayBuffer).

deserializer.getWireFormatVersion()‎

    • القيمة المُعادة: من النوع <integer>.

يقرأ إصدار تنسيق الأسلاك الأساسية. غالبًا ما يفيد في قراءة الشيفرات القديمة من الإصدارات القديمة لتنسيق الأسلاك. قد لا يستدعى قبل ‎.readHeader()‎.

deserializer.readUint32()‎

    • القيمة المُعادة: من النوع <integer>.

قراءة عدد صحيح 32 بت خام بدون إشارة. للاستخدام داخل أحد تخصيصات التابع deserializer._readHostObject()‎.

deserializer.readUint64()‎

    • القيمة المُعادة: من النوع <integer[]‎>.

قراءة عدد صحيح 64 بت خام بدون إشارة وإعادته كمصفوفة [hi, lo] تحتوي على عنصرين 32 بت بدون إشارة. للاستخدام داخل أحد تخصيصات التابع deserializer._readHostObject()‎.

deserializer.readDouble()‎

    • القيمة المُعادة: من النوع <number>.

قراءة قيمة من النوع number. للاستخدام داخل أحد تخصيصات التابع deserializer._readHostObject()‎.

deserializer.readRawBytes(length)‎ [المصدر]

    • length من النوع <integer>.

    • القيمة المُعادة: من النوع <Buffer>.

قراءة وحدات البايت الخام في المخزن المؤقت الداخلي لماسح التسلسل. يجب أن يقابل المعاملُ length طولَ المخزن المؤقت الذي سبق تمريره إلى التابع serializer.writeRawBytes()‎. للاستخدام داخل أحد تخصيصات التابع deserializer._readHostObject()‎.

deserializer._readHostObject()‎

ويُستدعى هذا التابع لقراءة نوع من الكائنات المضيفة، أي كائن مُنشأ بواسطة روابط C++‎ الأصلي. إذا لم يكن من الممكن إجراء تسلسل البيانات، يجب إجراء استثناء مناسب.

هذا التابع غير موجود ضمن الصنف Deserializer نفسه ولكن يمكن توفيره بواسطة الأصناف الفرعية.

الصنف: v8.DefaultSerializer

أُضيف مع الإصدار: v8.0.0.

صنف فرعي من Serializer الذي يُسلسل TypedArray (في Buffer معين) وكائنات DataView ككائنات مضيفة، ويخزن فقط جزء من ArrayBuffer الأساسية التي كانت تشير إليه.

الصنف: v8.DefaultDeserializer

أُضيف مع الإصدار: v8.0.0.

صنف فرعي من Deserializer ويقابل التنسيق المكتوب بواسطة DefaultSerializer.

مصادر

• صفحة الوحدة V8 في توثيق Node.js الرسمي.