الدرس 57: شرح الـ Stream في لغة دارت (Stream in Dart)

تستخدم Streams في لغة برمجة دارت لتمثيل تسلسل من الأحداث اللاحقة التي تحمل قيمًا متعددة وسوف تصل في المستقبل. يتعامل كلاس الـ Stream مع تسلسل الأحداث بدلاً من الأحداث الفردية. ويحتوي الـ Stream على واحد أو أكثر من المستمعين، وسيتلقى جميع المستمعين نفس القيمة.

مفهوم Stream (التدفق) في دارت

التدفق هو سلسلة من الأحداث اللاحقة التي تمثل قيم متعددة ستصل في المستقبل. في الـ Stream، يتم وضع القيمة في طرف واحد وإذا كان هناك مستمع في الطرف الآخر، سيرى المستمع تلك القيمة. يمكن أن تكون هذه الأحداث قيمًا لأي نوع، أو أخطاء، أو حدث “انتهاء” للإشارة إلى نهاية التدفق.

الفرق بين Sync و Async

• Sync Stream (تدفق متزامن): يعني أن القيم تصل بشكل متزامن وفقًا للترتيب.
• Async Stream (تدفق غير متزامن): يعني أن القيم تصل بشكل غير متزامن ويمكن أن تصل بأي ترتيب.

كيفية إنشاء Stream في دارت

يمكنك إنشاء Stream في لغة برمجة دارت باستخدام كلاس Stream. فيما يلي بعض الأمثلة:

كيفية إنشاء Stream باستخدام async*:

Stream<String> getUserName() async* {
  await Future.delayed(Duration(seconds: 1));
  yield 'Mark';
  await Future.delayed(Duration(seconds: 1));
  yield 'John';
  await Future.delayed(Duration(seconds: 1));
  yield 'Smith';
}

كيفية إنشاء Stream باستخدام Stream.fromIterable():

Stream<String> getUserName() {
  return Stream.fromIterable(['Mark', 'John', 'Smith']);
}

كيفية استخدام Stream في دارت

يمكنك استخدام Stream في لغة برمجة دارت باستخدام حلقة await for. فيما يلي مثال عن كيفية استخدام Stream في الطباعة:

void main() async {
  await for (String name in getUserName()) {
    print(name);
  }
}

الفرق بين Future و Stream

هنا بعض الفروق بين Future و Stream:

أنواع الـ Stream في دارت

هناك نوعين من الـ Stream:

Single Subscription Stream:

يتم تعيين الـ Streams للاشتراك الفردي بشكل افتراضي. فهي تحتفظ بالقيم حتى يشترك شخص ما ويمكن الاستماع إليها مرة واحدة فقط. سيحدث خطأ إذا حاولت الاستماع مرة أخرى. يجب عدم فقدان قيمة أي حدث ويجب أن تكون في الترتيب الصحيح. داخل وحدة تحكم الـ Stream، هناك Stream واحد فقط، ويمكن لمشترك واحد فقط استخدام هذا الـ Stream.

Broadcast Stream:

هذا هو الـ Stream الذي يتم تعيينه للاشتراك المتعدد. فهو يحتفظ بالقيم حتى يتمكن المشتركون من الاستماع عدة مرات. يمكنك استخدام الـ Broadcast Stream إذا كنت ترغب في أن يستمع المزيد من الكائنات إلى الـ Stream. يمكن استخدامه لأحداث الفأرة في المتصفح. داخل وحدة تحكم الـ Stream، يمكن استخدام العديد من الـ Streams بواسطة العديد من المشتركين. على سبيل المثال، يمكنك البدء في مشاهدة مقاطع الفيديو على مثل هذا الـ Stream في أي وقت، ويمكن لأكثر من مشترك مشاهدة الفيديو في نفس الوقت. بالمثل، يمكنك مشاهدته مرة أخرى بعد إلغاء الاشتراك السابق.

كيفية الاشتراك في الـ Stream:

يمكنك الاشتراك في الـ Stream بواسطة الدالة listen() التي تتلقى وظيفة تنفيذية تستدعى عندما يتم إرسال قيمة جديدة إلى الـ Stream. يمكنك أيضًا تحديد وظيفة للتعامل مع الأخطاء عن طريق استخدام onError وتحديد ما إذا كان يجب إغلاق الـ Stream عند حدوث خطأ باستخدام cancelOnError.

// إنشاء StreamController
StreamController<String> controller = StreamController<String>();

// الاشتراك في الـ Stream وتنفيذ وظيفة عندما يتم إرسال قيمة جديدة
StreamSubscription<String> subscription = controller.stream.listen(
  (value) {
    print(value);
  },
  onError: (error) {
    print('Error occurred: $error');
  },
  cancelOnError: false,
);

// إضافة قيمة إلى الـ Stream وإعلام المستمعين
controller.add('Hello');
controller.add('World');

// إلغاء الاشتراك
subscription.cancel();

// إغلاق الـ Stream بعد الانتهاء
controller.close();

كيفية إدارة الـ Stream:

يمكنك إدارة الـ Stream باستخدام الدوال المتاحة في كلاس StreamController، مثل add(), addError(), close(), و stream. يمكنك أيضًا مراقبة حالة الـ Stream باستخدام الدوال hasListener و isClosed.

// إنشاء StreamController
StreamController<int> controller = StreamController<int>();

// إضافة قيمة إلى الـ Stream
controller.add(1);
controller.add(2);
controller.add(3);

// إضافة خطأ إلى الـ Stream
controller.addError('Error occurred');

// إغلاق الـ Stream
controller.close();

// التحقق مما إذا كان هناك مستمع في الـ Stream
print('Has Listener: ${controller.hasListener}');

// التحقق مما إذا تم إغلاق الـ Stream
print('Is Closed: ${controller.isClosed}');

كيفية إلغاء الاشتراك في الـ Stream:

يمكن إلغاء الاشتراك في الـ Stream باستخدام دالة cancel() التي تتوقف عن استلام القيم الجديدة. يمكن استخدام المتغير الذي يحتوي على الاشتراك الفعلي لإلغاء الاشتراك.

// إنشاء StreamController
StreamController<String> controller = StreamController<String>();

// الاشتراك في الـ Stream وتنفيذ وظيفة عندما يتم إرسال قيمة جدية
StreamSubscription<String> subscription = controller.stream.listen(
  (value) {
    print(value);
  },
);

// إلغاء الاشتراك
subscription.cancel();

// إضافة قيمة إلى الـ Stream (لن يتم استقبالها بسبب إلغاء الاشتراك)
controller.add('Hello');

// إغلاق الـ Stream بعد الانتهاء
controller.close();

هذا هو مثال بسيط عن كيفية استخدام Stream و StreamController في لغة البرمجة Dart. يمكنك تعديل الأمثلة حسب احتياجاتك وتطبيقها في سياق برنامجك.

أنواع الكلاسات في الـ Stream

في لغة دارت (Dart)، هناك أربعة كلاسات رئيسية تستخدم لإدارة الـ Stream بشكل فعال. سنتعرف على هذه الكلاسات ونشرح كيفية استخدامها فيما يلي:

كلاس Stream:

يُمثِّل الـ Stream تدفقًا غير متزامن للبيانات. وهو يُعد واجهة للتعامل مع تدفق البيانات بشكل غير متزامن. وعلى سبيل المثال، يمكن استخدامه لتمثيل تدفق الأحداث أو القيم التي تصل في المستقبل. يتميز الـ Stream بأنه يمكن أن يحتوي على قيمة واحدة أو أكثر، ويمكن أن يحمل قيمًا من أي نوع، بالإضافة إلى إمكانية إرسال أحداث الخطأ وحدث “تم الانتهاء” (done) للإشارة إلى نهاية التدفق.

// Excerpt from the code example
final controller = StreamController<String>();

final subscription = controller.stream.listen((String data) {
  print(data);
});

controller.sink.add("Data!");

نلاحظ في المثال أعلاه إنشاء Stream من خلال استخدام StreamController. يتم استخدام StreamController لإنشاء وإدارة الـ Stream، وبعد ذلك يمكننا الوصول إلى الـ Stream من خلال controller.stream.

كلاس EventSink:

يشبه الـ Stream في اتجاه تدفق البيانات المعاكس. فبدلاً من تدفق البيانات من المُنتج (producer) إلى المستهلك (consumer) كما هو الحال في الـ Stream، يمكن استخدام الـ EventSink لتدفق البيانات من المستهلك إلى المُنتج.

كلاس StreamController:

يُسهِّل StreamController إدارة الـ Stream بشكل أكثر سهولة ويُساعد على إنشاء الـ Stream والـ Sink تلقائيًا، بالإضافة إلى توفير طرق للتحكم في سلوك التدفق. يمكن استخدام StreamController لإنشاء Stream وإضافة القيم إلى الـ Stream وإدارة الاشتراكات وإلغائها.

// Excerpt from the code example
final controller = StreamController<String>();

كلاس StreamSubscription:

يُستخدَم لحفظ مراجع الاشتراكات ويسمح بإيقاف واستئناف أو إلغاء تدفق البيانات التي يتلقاها. يمكن استخدامه لإيقاف مؤقت للتدفق أو استئنافه أو إلغائه تمامًا.

هذه هي الكلاسات الرئيسية المستخدمة في إدارة الـ Stream في لغة دارت. يمكن استخدامها بشكل فعال للتعامل مع التدفقات الغير متزامنة وتنظيمها بطريقة سهلة ومرنة.

الدوال المستخدمة في الـ Stream

هنا بعض الدوال المستخدمة في الـ Stream:

• listen(): تُستخدم للاشتراك في الـ Stream وتقوم بتعيين callback function لمعالجة الأحداث المُرسلة.
• onError: تُستخدم لتعيين callback function التي ستتم استدعاؤها عند حدوث خطأ في الـ Stream.
• cancelOnError: تُستخدم لتحديد ما إذا كان يجب إلغاء الاشتراك تلقائيًا عند حدوث خطأ في الـ Stream أم لا.
• onDone: تُستخدم لتعيين callback function التي ستتم استدعاؤها عند اكتمال الـ Stream وإغلاقه.

الكلمات المستخدمة في الـ Stream

هنا بعض الكلمات المستخدمة في الـ Stream:

• async: تُستخدم لتعيين الدالة كـ asynchronous وتسمح باستخدام yield.
• async*: تُستخدم لتعيين الدالة كـ asynchronous generator وتسمح باستخدام yield.
• yield: تُستخدم لإرجاع قيمة من الـ Stream.

أمثلة على الـ Stream في لغة دارت:

مثال 1: استخدام async* في لغة دارت

في هذا المثال، سنقوم بإنشاء Stream يقوم بإرجاع أعداد صحيحة تزداد بشكل تدريجي بفاصل زمني، ولكن باستخدام asynchronous generator:

import 'dart:async';

void main() {
  Stream<int> countStream() async* {
    int count = 0;
    while (count < 5) {
      await Future.delayed(Duration(seconds: 1));
      yield count;
      count++;
    }
  }

  countStream().listen((value) {
    print(value);
  });
}

في هذا المثال، تم استخدام الكلمة الأساسية async* لتعيين الدالة countStream كـ asynchronous generator. تم استخدام كلمة yield لإرجاع قيمة count إلى الـ Stream في كل دورة.

مثال 2: الاشتراك في Stream للحصول على القيم الفردية

Stream<int> countStream() async* {
  for (int i = 1; i <= 5; i++) {
    await Future.delayed(Duration(seconds: 1));
    yield i;
  }
}

void main() {
  final stream = countStream();
  final subscription = stream.listen((value) {
    print(value);
  });

  // إلغاء الاشتراك بعد 3 ثواني
  Future.delayed(Duration(seconds: 3), () {
    subscription.cancel();
  });
}

مثال 3: تحويل Stream إلى List

void main() {
  final stream = Stream.fromIterable([1, 2, 3, 4, 5]);
  stream.toList().then((list) {
    print(list); // [1, 2, 3, 4, 5]
  });
}

مثال 4: تجاهل قيم معينة في Stream باستخدام where

void main() {
  final stream = Stream.fromIterable([1, 2, 3, 4, 5]);
  stream.where((value) => value.isOdd).listen((value) {
    print(value); // 1, 3, 5
  });
}

مثال 5: دمج عدة Streams باستخدام merge

import 'dart:async';

void main() {
  final stream1 = Stream.periodic(Duration(seconds: 1), (value) => value + 1).take(5);
  final stream2 = Stream.fromIterable([6, 7, 8, 9, 10]);

  final mergedStream = StreamGroup.merge([stream1, stream2]);
  mergedStream.listen((value) {
    print(value); // 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
  });
}

مثال 6: تحويل Stream إلى Map باستخدام asyncMap

void main() {
  final stream = Stream.fromIterable([1, 2, 3, 4, 5]);
  stream.asyncMap((value) async => {'number': value}).listen((value) {
    print(value); // {'number': 1}, {'number': 2}, {'number': 3}, {'number': 4}, {'number': 5}
  });
}

هذه بعض الأمثلة الإضافية لاستخدام Stream و StreamController في لغة البرمجة Dart. يمكنك استخدام هذه الأمثلة لفهم المزيد عن كيفية استخدام Streams في تطبيقاتك الخاصة.

هذه هي بعض المعلومات الأساسية حول كيفية إضافة قيمة إلى الـ Stream وإدارته. يمكنك استكشاف المزيد من الوظائف والميزات المتاحة في حزمة dart:async للتعامل مع الـ Stream بشكل أكثر تفصيلاً.