From 32f49dc8a0b817f08ed3db0260a417a5201b3db4 Mon Sep 17 00:00:00 2001 From: Hisham Mahgoub Date: Tue, 26 May 2026 00:06:45 +0300 Subject: [PATCH 1/3] changes on the english documentation structure --- README.md | 207 ++++++++++++++++++------------------------------------ 1 file changed, 67 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index ed31c64..829212e 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ Provides threading and thread synchronization functionality. ## Adding to the Project + + Use the following lines: ``` @@ -12,229 +14,155 @@ import "Apm"; Apm.importPackage("Alusus/Threading@0.1"); ``` - ## Functions + + ### createThread + ``` - func createThread( - pthread: ptr[Thread], attr: ptr[ThreadAttributes], startRoutine: ptr[func (ptr): ptr], arg: ptr - ): Int; +func createThread(pthread: ptr[Thread], attr: ptr[ThreadAttributes], startRoutine: ptr[func (ptr): ptr], arg: ptr): Int ``` -A function to create a thread. This function is equivalent to Posix `pthread_create`. - -Arguments: +Create a thread. This function is equivalent to Posix `pthread_create`. Returns 0 on success, an error code otherwise. * `pthread`: A pointer to a variable of type Thread, in which the result is stored. * `attr`: The attributes we want for the thread. Passing null indicates default attributes. * `startRoutine`: A pointer to a function that will be executed on this thread. -* `arg`: An arbitrary pointer to pass to the function in the preceding argument. This is used to pass user data to the - thread. - -Return Value: - -Returns 0 on success, an error code otherwise. +* `arg`: An arbitrary pointer to pass to the function in the preceding argument. This is used to pass user data to the thread. ### joinThread + ``` - func joinThread(pthread: ptr[Thread], retval: ptr[ptr]): Int; +func joinThread(pthread: ptr[Thread], retval: ptr[ptr]): Int ``` -Waits for a thread to finish execution. This function is equivalent to Posix `pthread_join`. - -Arguments: +Waits for a thread to finish execution. This function is equivalent to Posix `pthread_join`. Returns 0 on success, an error code otherwise. * `pthread`: A pointer to the thread to wait for. -* `retval`: A pointer to store the result of executing the given thread's function. This will contain the value - returned by the thread function. - -Return Value: - -Returns 0 on success, an error code otherwise. +* `retval`: A pointer to store the result of executing the given thread's function. This will contain the value returned by the thread function. ### initMutex + ``` - func initMutex(mutex: ptr[Mutex], attrs: ptr[MutexAttributes]): Int; +func initMutex(mutex: ptr[Mutex], attrs: ptr[MutexAttributes]): Int ``` -Initializes a mutex lock. A mutex must be initialized by this function before it can be used. This function is -equivalent to Posix `pthread_mutex_init`. - -Arguments: +Initializes a mutex lock. A mutex must be initialized by this function before it can be used. This function is equivalent to Posix `pthread_mutex_init`. Returns 0 on success, an error code otherwise. * `mutex`: A pointer to the Mutex object. * `attrs`: Attributes for this mutex. Passing null indicates default attributes. -Return Value: - -Returns 0 on success, an error code otherwise. - ### lockMutex + ``` - func lockMutex(mutex: ptr[Mutex]): Int; +func lockMutex(mutex: ptr[Mutex]): Int ``` -Locks the mutex object. If the mutex is locked by another thread the current thread will be paused until the mutex is -available. This function is equivalent to Posix `pthread_mutex_lock`. - -Arguments: +Locks the mutex object. If the mutex is locked by another thread the current thread will be paused until the mutex is available. This function is equivalent to Posix `pthread_mutex_lock`. Returns 0 on success, an error code otherwise. * `mutex`: A pointer to the Mutex object. -Return Value: - -Returns 0 on success, an error code otherwise. - ### tryLockMutex + ``` - func tryLockMutex(mutex: ptr[Mutex]): Int; +func tryLockMutex(mutex: ptr[Mutex]): Int ``` -Locks the mutex object. If the mutex is locked by another thread the function returns immediately with an error code. -This function is equivalent to Posix `pthread_mutex_trylock`. - -Arguments: +Locks the mutex object. If the mutex is locked by another thread the function returns immediately with an error code. This function is equivalent to Posix `pthread_mutex_trylock`. Returns 0 on success, an error code otherwise. * `mutex`: A pointer to the Mutex object. -Return Value - -Returns 0 on success, an error code otherwise. - ### unlockMutex + ``` - func unlockMutex(mutex: ptr[Mutex]): Int; +func unlockMutex(mutex: ptr[Mutex]): Int ``` -Unlocks a mutex. This function is equivalent to Posix `pthread_mutex_unlock`. - -Arguments: +Unlocks a mutex. This function is equivalent to Posix `pthread_mutex_unlock`. Returns 0 on success, an error code otherwise. * `mutex`: A pointer to the Mutex object. -Return Value - -Returns 0 on success, an error code otherwise. - ### initCond + ``` - func initCond(cond: ptr[Cond], attrs: ptr[CondAttributes]): Int; +func initCond(cond: ptr[Cond], attrs: ptr[CondAttributes]): Int ``` -Initializes a condition object. A condition must be initialized by this function before it can be used. -This function is equivalent to Posix `pthread_cond_init`. - -Arguments: +Initializes a condition object. A condition must be initialized by this function before it can be used. This function is equivalent to Posix `pthread_cond_init`. Returns 0 on success, an error code otherwise. * `cond`: A pointer to the Cond object. * `attrs`: Attributes for this condition. Passing null indicates default attributes. -Return Value: - -Returns 0 on success, an error code otherwise. - ### signalCond + ``` - func signalCond(cond: ptr[Cond]): Int; +func signalCond(cond: ptr[Cond]): Int ``` -Sends a signal that a condition is met. This will unlock one thread that is waiting on this condition. If multiple -threads are waiting for the same condition only one of them will be released per call. Before calling this function -the calling thread must first lock a mutex (the same mutex used by the thread in `waitCond`) and must release the -mutex after the call. The thread calling `waitCond` will only be released after the mutex is released since the -`waitCond` will attempt to lock the mutex before returning. -This is equivalent to Posix `pthread_cond_signal`. - -Arguments: +Sends a signal that a condition is met. This will unlock one thread that is waiting on this condition. If multiple threads are waiting for the same condition only one of them will be released per call. Before calling this function the calling thread must first lock a mutex (the same mutex used by the thread in `waitCond`) and must release the mutex after the call. The thread calling `waitCond` will only be released after the mutex is released since the `waitCond` will attempt to lock the mutex before returning. This is equivalent to Posix `pthread_cond_signal`. Returns 0 on success, an error code otherwise. * `cond`: A pointer to the condition object to signal. -Return Value: - -Returns 0 on success, an error code otherwise. - ### waitCond + ``` - func waitCond(cond: ptr[Cond], mutex: ptr[Mutex]): Int; +func waitCond(cond: ptr[Cond], mutex: ptr[Mutex]): Int ``` -Waits for a condition to be met. This takes a mutex in addition to the condition to wait for, and it requires that the -mutex is locked before the call. The function will atomically block the thread and release the mutex. When the condition -is signaled the function will atomically re-lock the mutex and release the calling thread. -This function is equivalent to Posix `pthread_cond_wait`. - -Arguments: +Waits for a condition to be met. This takes a mutex in addition to the condition to wait for, and it requires that the mutex is locked before the call. The function will atomically block the thread and release the mutex. When the condition is signaled the function will atomically re-lock the mutex and release the calling thread. This function is equivalent to Posix `pthread_cond_wait`. Returns 0 on success, an error code otherwise. * `cond`: A pointer to the Cond object to wait on. * `mutex`: A pointer to a Mutex object. This must be locked before calling this function. -Return Value: - -Returns 0 on success, an error code otherwise. +## Types -## Types ### ThreadAttributes -``` -class ThreadAttributes { - def flags: Int; - def stackSize: Int; - def contentionScope: Int; - def inheritSched: Int; - def detachState: Int; - def sched: Int; - def param: SchedParam; - def startTime: TimeSpec; - def deadLine: TimeSpec; - def period: TimeSpec; -} -``` +* `flags` (`Int`) +* `stackSize` (`Int`) +* `contentionScope` (`Int`) +* `inheritSched` (`Int`) +* `detachState` (`Int`) +* `sched` (`Int`) +* `param` (`SchedParam`) +* `startTime` (`TimeSpec`) +* `deadLine` (`TimeSpec`) +* `period` (`TimeSpec`) ### SchedParam -``` -class SchedParam { - def schedPriority: Int; -} -``` +* `schedPriority` (`Int`) ### TimeSpec -``` -class TimeSpec { - def tvSec: ArchInt; - def tvNsec: Int[64]; -} -``` +* `tvSec` (`ArchInt`) +* `tvNsec` (`Int[64]`) ### Mutex Used for synchronizing threads by allowing threads to request locking the mutex and release the lock after the thread is done with the synchronized work. -* `init`: Initializes the mutex. This must be called before the mutex is usable. It has two forms: +#### init ``` -handler this.init(); -handler this.init(attr: ref[MutexAttributes]); +handler this.init() +handler this.init(attr: ref[MutexAttributes]) ``` +Initializes the mutex. This must be called before the mutex is usable. + +#### lock -* `lock`: Locks the mutex. This will freeze the thread until the lock is available. +Locks the mutex. This will freeze the thread until the lock is available. -* `unlock`: Unlocks the mutex allowing the OS to release another waiting thread. +#### unlock + +Unlocks the mutex allowing the OS to release another waiting thread. ### MutexAttributes -``` -class MutexAttributes { - def pshared: Int = 0; - def kind: Int = 0; - def protocol: Int = 0; - def robustness: Int = 0; -} -``` +* `pshared` (`Int`) +* `kind` (`Int`) +* `protocol` (`Int`) +* `robustness` (`Int`) ### CondAttributes -``` -class CondAttributes { - def dummy: Int = 0; -} -``` +* `dummy` (`Int`) ### ThreadLocal @@ -244,8 +172,7 @@ thread but aren't shared between threads. * `initializer`: A closure used to initialize the variable. It's called automatically when the variable is created within a thread, i.e. it's called for each thread in which the variable is created. If this closure isn't set the variable will only be initialized using the - built-in constructor. This `initializer` can be set by passing it to the constructor - of `ThreadLocal` or by setting the `initializer` member value directly. + built-in constructor. This `initializer` can be set by passing it to the constructor of `ThreadLocal` or by setting the `initializer` member value directly. * `value`: Used to access the actual value. Accessing this attribute for the first time within a thread will result in allocating and initializing the variable before returning a reference @@ -265,9 +192,10 @@ Console.print(var.value.i); In this example `var` is declared to contain a value of type `MyType`. When the variable of type `MyType` is created within a thread its `i` attribute will be set to a random value. - ## Example + + ``` import "Srl/Console"; import "Apm"; @@ -326,9 +254,8 @@ func calculateSum(p: ptr): ptr { totalSum(); ``` ---- - ## License -This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the `COPYING` and `COPYING.LESSER` files for details. + +This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the `COPYING` and `COPYING.LESSER` files for details. From cc166b696e0adaec358cfeffe83c964e7eb93a83 Mon Sep 17 00:00:00 2001 From: Hisham Mahgoub Date: Sun, 31 May 2026 19:23:57 +0300 Subject: [PATCH 2/3] restructure Arabic and English READMEs format --- README.ar.md | 372 +++++++++++++++++++++++++++++++++++++++++++-------- README.md | 167 ++++++++++++++++++++--- 2 files changed, 463 insertions(+), 76 deletions(-) diff --git a/README.ar.md b/README.ar.md index be9362a..790c83d 100644 --- a/README.ar.md +++ b/README.ar.md @@ -1,33 +1,34 @@ # تـوازي (Threading) [[English]](README.md) + +
+ مكتبة لإنشاء المسالك (threads) وتمكين المزامنة (synchronization) بينها في لغة الأسس. ## إضافة المكتبة للمشروع أضف المكتبة لمشروعك باستخدام مدير الحزم: -
- ``` اشمل "مـحا"؛ مـحا.اشمل_حزمة("Alusus/Threading@0.1"، "تـوازي.أسس")؛ ``` -
+
``` import "Apm"; Apm.importPackage("Alusus/Threading@0.1"); ``` +
+ ## الدالات ### أنشئ_مسلكا (createThread) -
- ``` دالة أنشئ_مسلكا( مسلك: مؤشر[مـسلك]، @@ -37,7 +38,7 @@ Apm.importPackage("Alusus/Threading@0.1"); ): صـحيح؛ ``` -
+
``` func createThread( @@ -47,7 +48,10 @@ Apm.importPackage("Alusus/Threading@0.1"); arg: ptr ): Int; ``` -دالة لإنشاء مسلك. تطابق هذه الدالة دالة `pthread_create` من Posix. + +
+ +دالة لإنشاء مسلك. تطابق هذه الدالة دالة `pthread_create` من Posix. المعطيات: @@ -65,17 +69,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### التق_بمسلك (joinThread) -
- ``` دالة التق_بمسلك(مسلك: مؤشر[مـسلك]، نتيجة: مؤشر[مؤشر]): صـحيح؛ ``` -
+
``` func joinThread(pthread: ptr[Thread], retval: ptr[ptr]): Int; ``` + +
+ تنتظر مسلكا حتى يكتمل تنفيذه وتستلم منه القيمة المرجعة من دالة المسلك. هذه الدالة تطابق دالة `pthread_join` من Posix. المعطيات: @@ -90,17 +95,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### هيئ_مزامنا (initMutex) -
- ``` دالة هيئ_مزامنا(مزامن: مؤشر[مـزامن]، مزايا: مؤشر[مـزايا_مزامن]): صـحيح؛ ``` -
+
``` func initMutex(mutex: ptr[Mutex], attrs: ptr[MutexAttributes]): Int; ``` + +
+ تهيئ مزامنا. يجب تهيئة المزامن باستخدام هذه الدالة قبل التمكن من استخدامه. هذه الدالة تطابق دالة `pthread_mutex_init` من Posix. @@ -116,17 +122,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### اقفل_مزامنا (lockMutex) -
- ``` دالة اقفل_مزامنا(مزامن: مؤشر[مـزامن]): صـحيح؛ ``` -
+
``` func lockMutex(mutex: ptr[Mutex]): Int; ``` + +
+ تقفل المزامن وتحجزه للمسلك الحالي. إن كان المزامن محجوزا من قبل مسلك آخر فسيُجمد هذا المسلك حتى يتم تحرير المزامن من قبل المسلك الآخر. هذه الدالة تطابق دالة `pthread_mutex_lock` من Posix. @@ -140,17 +147,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### حاول_قفل_مزامن (tryLockMutex) -
- ``` دالة حاول_قفل_مزامن(مزامن: مؤشر[مـزامن]): صـحيح؛ ``` -
+
``` func tryLockMutex(mutex: ptr[Mutex]): Int; ``` + +
+ تقفل المزامن إذا كان حرًا، وتُرجع رمز خطأ مباشرة دون انتظار إذا كان المزامن محجوزًا من قبل مسلك آخر. هذه الدالة تطابق دالة `pthread_mutex_trylock` من Posix. @@ -164,17 +172,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### افتح_مزامنا (unlockMutex) -
- ``` دالة افتح_مزامنا(مزامن: مؤشر[مـزامن]): صـحيح؛ ``` -
+
``` func unlockMutex(mutex: ptr[Mutex]): Int; ``` + +
+ تحرر مزامنًا وتجعله متوفرًا للمسالك الأخرى. هذه الدالة تطابق دالة `pthread_mutex_unlock` من Posix. المعطيات: @@ -187,23 +196,24 @@ Apm.importPackage("Alusus/Threading@0.1"); ### هيئ_شرطا (initCond) -
- ``` دالة هيئ_شرطا(شرط: مؤشر[شـرط]، مزايا: مؤشر[مـزايا_شرط]): صـحيح؛ ``` -
+
``` func initCond(cond: ptr[Cond], attrs: ptr[CondAttributes]): Int; ``` + +
+ يهيئ كائنا من صنف `شـرط`. يجب تهيئة الشرط بهذه الدالة قبل استخدامه. هذه الدالة تطابق دالة `pthread_cond_init` من Posix. المعطيات: -`شرد`: مؤشر إلى الشرط المراد تهيئته. +`شرط`: مؤشر إلى الشرط المراد تهيئته. `مزايا`: المزايا المطلوبة للشرط. تمرير 0 يؤدي إلى تهيئته بالمزايا الافتراضية. @@ -213,17 +223,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### علم_شرطا (signalCond) -
- ``` دالة علم_شرطا(شرط: مؤشر[شـرط]): صـحيح؛ ``` -
+
``` func signalCond(cond: ptr[Cond]): Int; ``` + +
+ يُرسل إشارة بأن الشرط المعني قد تحقق. يؤدي ذلك لتحرير مسلك واحد من المسالك المنتظرة لهذا الشرط. إن وُجد عدة مسالك تنتظر الشرط فسيُحرر واحد منها فقط لكل استدعاء لهذه الدالة. قبل استدعاء هذه الدالة يجب على المسلك قفل مزامن (نفس المزامن المستخدم من قبل المسالك التي تستدعي `انتظر_شرطا` `waitCond`) ويجب تحرير @@ -241,17 +252,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### انتظر_شرطا (waitCond) -
- ``` دالة انتظر_شرطا(شرط: مؤشر[شـرط]، مزامن: مؤشر[مـزامن]): صـحيح؛ ``` -
+
``` func waitCond(cond: ptr[Cond], mutex: ptr[Mutex]): Int; ``` + +
+ تنتظر تحقق شرط. تستقبل هذه الدالة مزامنا بالإضافة إلى الشرط المعني وتتطلب أن يكون المزامن مقفلًا قبل استداءها. تعمل الدالة بشكل لا انشطاري (atomic) على تجميد المسلك وتحرير المزامن. عند تحقق الشرط تقوم الدالة بشكل لا انشطاري بقفل المزامن مجددًا وتحرير المسلك. @@ -272,8 +284,6 @@ Apm.importPackage("Alusus/Threading@0.1"); ### مـزايا_مسلك (ThreadAttributes) -
- ``` صنف مـزايا_مسلك { عرف أعلام: صـحيح؛ @@ -289,7 +299,7 @@ Apm.importPackage("Alusus/Threading@0.1"); } ``` -
+
``` class ThreadAttributes { @@ -306,17 +316,157 @@ class ThreadAttributes { } ``` -### مـعامل_جدولة (SchedParam) +
-
+#### أعلام (flags) + +``` +عرف أعلام: صـحيح؛ +``` + +
+ +``` +def flags: Int; +``` + +
+ +#### حجم_المكدس (stackSize) + +``` +عرف حجم_المكدس: صـحيح؛ +``` + +
+ +``` +def stackSize: Int; +``` + +
+ +#### مجال_التنافس (contentionScope) + +``` +عرف مجال_التنافس: صـحيح؛ +``` + +
+ +``` +def contentionScope: Int; +``` + +
+ +#### توريث_الجدولة (inheritSched) + +``` +عرف توريث_الجدولة: صـحيح؛ +``` + +
+ +``` +def inheritSched: Int; +``` + +
+ +#### فصل_الحالة (detachState) + +``` +عرف فصل_الحالة: صـحيح؛ +``` + +
+ +``` +def detachState: Int; +``` + +
+ +#### جدولة (sched) + +``` +عرف جدولة: صـحيح؛ +``` + +
+ +``` +def sched: Int; +``` + +
+ +#### معلمة (param) + +``` +عرف معلمة: مـعامل_جدولة؛ +``` + +
+ +``` +def param: SchedParam; +``` + +
+ +#### وقت_البداية (startTime) + +``` +عرف وقت_البداية: تـفصيل_زمني؛ +``` + +
+ +``` +def startTime: TimeSpec; +``` + +
+ +#### حد_اقصى (deadLine) + +``` +عرف حد_اقصى: تـفصيل_زمني؛ +``` + +
+ +``` +def deadLine: TimeSpec; +``` + +
+ +#### فترة (period) + +``` +عرف فترة: تـفصيل_زمني؛ +``` + +
+ +``` +def period: TimeSpec; +``` + +
+ +### مـعامل_جدولة (SchedParam) ``` صنف مـعامل_جدولة { عرف أولوية_الجدولة: صـحيح؛ -}؛ +} ``` -
+
``` class SchedParam { @@ -324,9 +474,23 @@ class SchedParam { } ``` -### تـفصيل_زمني (TimeSpec) +
-
+#### أولوية_الجدولة (schedPriority) + +``` +عرف أولوية_الجدولة: صـحيح؛ +``` + +
+ +``` +def schedPriority: Int; +``` + +
+ +### تـفصيل_زمني (TimeSpec) ``` صنف تـفصيل_زمني { @@ -335,7 +499,7 @@ class SchedParam { } ``` -
+
``` class TimeSpec { @@ -344,34 +508,71 @@ class TimeSpec { } ``` +
+ +#### مدة_ثواني (tvSec) + +``` +عرف مدة_ثواني: صـحيح_متكيف؛ +``` + +
+ +``` +def tvSec: ArchInt; +``` + +
+ +#### مدة_نانو (tvNsec) + +``` +عرف مدة_نانو: صـحيح[64]؛ +``` + +
+ +``` +def tvNsec: Int[64]; +``` + +
+ ### مـزامن (Mutex) يستخدم للمزامنة بين المسالك المختلفة ويتم ذلك بطلب المسلك قفل المزامن، ومن ثم بعد الحصول على القفل يقوم بالعمل المراد ثم يحرر القفل ليتسنى لمسلك آخر قفله. -* `هيئ`: دالة لتهيئة المزامن. يجب استدعاء هذه الدالة قبل استخدام المزامن. لها صيغتان: - -
+#### هيئ (init) ``` عملية هذا.هيئ()؛ عملية هذا.هيئ(مزايا: سند[مـزايا_مزامن])؛ ``` -
+
``` -handler this.init(); -handler this.init(attr: ref[MutexAttributes]); +handler this.init() +handler this.init(attr: ref[MutexAttributes]) ``` -* `اقفل`: تستخدم لقفل المزامن ولا تستلم أي معطيات. عند استدعاء هذه الدالة يُلبث المسلك لحين تحرر هذا - المزامن من أي قفل. +
+ +دالة لتهيئة المزامن. يجب استدعاء هذه الدالة قبل استخدام المزامن. + +#### اقفل (lock) + +تستخدم لقفل المزامن ولا تستلم أي معطيات. عند استدعاء هذه الدالة يُلبث المسلك لحين تحرر هذا المزامن من أي قفل. -* `افتح`: تفتح القفل ما يتيح لنظام التشغيل تحرير أحد المسالك المُنتظِرة لهذا القفل. +#### افتح (unlock) + +تفتح القفل ما يتيح لنظام التشغيل تحرير أحد المسالك المُنتظِرة لهذا القفل. ### مـزايا_مزامن (MutexAttributes) +
+ ``` class MutexAttributes { def pshared: Int = 0; @@ -381,14 +582,70 @@ class MutexAttributes { } ``` +
+ +#### pshared + +
+ +``` +def pshared: Int; +``` + +
+ +#### kind + +
+ +``` +def kind: Int; +``` + +
+ +#### protocol + +
+ +``` +def protocol: Int; +``` + +
+ +#### robustness + +
+ +``` +def robustness: Int; +``` + +
+ ### مـزايا_شرط (CondAttributes) +
+ ``` class CondAttributes { def dummy: Int = 0; } ``` +
+ +#### dummy + +
+ +``` +def dummy: Int; +``` + +
+ ### مـحلي_لمسلك (ThreadLocal) قالب أصناف يستخدم لإنشاء متغيرات محلية نسبة إلى مسلك، أي عمومية ضمن مسلك معين لكنها لا تُشارك مع @@ -405,8 +662,6 @@ class CondAttributes { المثال التالي يوضح استخدام هذا القالب: -
- ``` عرف متغير: تـوازي.مـحلي_لمسلك[صـنفي](مغلفة(م: سند[صـنفي]) { م.ع = ريـاضيات.عشوائي()؛ @@ -416,7 +671,7 @@ class CondAttributes { طـرفية.اطبع(متغير.القيمة.ع)؛ ``` -
+
``` def var: Threading.ThreadLocal[MyType](closure (val: ref[A]) { @@ -427,14 +682,14 @@ def var: Threading.ThreadLocal[MyType](closure (val: ref[A]) { Console.print(var.value.i); ``` +
+ في هذا المثال نعرف `متغير` (`var`) ليحتوي على قيمة من صنف `صـنفي` (`MyType`) وعند إنشاء المتغير ذو الصنف `صـنفي` ضمن مسلك معين تُحدد قيمة الخصلة `ع` (`i`) منه بقيمة عشوائية. ## مثال -
- ``` اشمل "مـتم/طـرفية"؛ اشمل "مـحا"؛ @@ -492,7 +747,7 @@ Console.print(var.value.i); مجموع_كلي(); ``` -
+
``` import "Srl/Console"; @@ -552,9 +807,12 @@ func calculateSum(p: ptr): ptr { totalSum(); ``` +
+ --- ## الرخصة هذا المشروع مرخص بموجب رخصة غنو العمومية الصغرى الإصدار 3.0 (LGPL-3.0). راجع ملفات `COPYING` و `COPYING.LESSER` للحصول على التفاصيل. +
diff --git a/README.md b/README.md index 829212e..6aa4792 100644 --- a/README.md +++ b/README.md @@ -108,29 +108,118 @@ Waits for a condition to be met. This takes a mutex in addition to the condition ## Types +### ThreadAttributes + +``` +class ThreadAttributes { + def flags: Int; + def stackSize: Int; + def contentionScope: Int; + def inheritSched: Int; + def detachState: Int; + def sched: Int; + def param: SchedParam; + def startTime: TimeSpec; + def deadLine: TimeSpec; + def period: TimeSpec; +} +``` +#### flags -### ThreadAttributes +``` +def flags: Int; +``` + +#### stackSize + +``` +def stackSize: Int; +``` -* `flags` (`Int`) -* `stackSize` (`Int`) -* `contentionScope` (`Int`) -* `inheritSched` (`Int`) -* `detachState` (`Int`) -* `sched` (`Int`) -* `param` (`SchedParam`) -* `startTime` (`TimeSpec`) -* `deadLine` (`TimeSpec`) -* `period` (`TimeSpec`) +#### contentionScope + +``` +def contentionScope: Int; +``` + +#### inheritSched + +``` +def inheritSched: Int; +``` + +#### detachState + +``` +def detachState: Int; +``` + +#### sched + +``` +def sched: Int; +``` + +#### param + +``` +def param: SchedParam; +``` + +#### startTime + +``` +def startTime: TimeSpec; +``` + +#### deadLine + +``` +def deadLine: TimeSpec; +``` + +#### period + +``` +def period: TimeSpec; +``` ### SchedParam -* `schedPriority` (`Int`) +``` +class SchedParam { + def schedPriority: Int; +} +``` + +#### schedPriority + +``` +def schedPriority: Int; +``` ### TimeSpec -* `tvSec` (`ArchInt`) -* `tvNsec` (`Int[64]`) +``` +class TimeSpec { + def tvSec: ArchInt; + def tvNsec: Int[64]; +} +``` + +#### tvSec + +``` +def tvSec: ArchInt; +``` + +#### tvNsec + +``` +def tvNsec: Int[64]; +``` + ### Mutex @@ -155,14 +244,54 @@ Unlocks the mutex allowing the OS to release another waiting thread. ### MutexAttributes -* `pshared` (`Int`) -* `kind` (`Int`) -* `protocol` (`Int`) -* `robustness` (`Int`) +``` +class MutexAttributes { + def pshared: Int = 0; + def kind: Int = 0; + def protocol: Int = 0; + def robustness: Int = 0; +} +``` + +#### pshared + +``` +def pshared: Int; +``` + +#### kind + +``` +def kind: Int; +``` + +#### protocol + +``` +def protocol: Int; +``` + +#### robustness + +``` +def robustness: Int; +``` ### CondAttributes -* `dummy` (`Int`) +``` +class CondAttributes { + def dummy: Int = 0; +} +``` + +#### dummy + +``` +def dummy: Int; +``` + + ### ThreadLocal From aab5c16bdc9beff4abe775a19c9001365333d298 Mon Sep 17 00:00:00 2001 From: Hisham Mahgoub Date: Tue, 2 Jun 2026 22:54:12 +0300 Subject: [PATCH 3/3] add spaces and add some missing definitions --- README.ar.md | 256 ++++++++++++++++++++++++++------------------------- README.md | 48 +++++++--- 2 files changed, 168 insertions(+), 136 deletions(-) diff --git a/README.ar.md b/README.ar.md index 790c83d..8d706fc 100644 --- a/README.ar.md +++ b/README.ar.md @@ -1,8 +1,6 @@ # تـوازي (Threading) -[[English]](README.md) - -
+[[English]](README.md) مكتبة لإنشاء المسالك (threads) وتمكين المزامنة (synchronization) بينها في لغة الأسس. @@ -10,12 +8,14 @@ أضف المكتبة لمشروعك باستخدام مدير الحزم: +
+ ``` اشمل "مـحا"؛ مـحا.اشمل_حزمة("Alusus/Threading@0.1"، "تـوازي.أسس")؛ ``` -
+
``` import "Apm"; @@ -24,11 +24,12 @@ Apm.importPackage("Alusus/Threading@0.1");
- ## الدالات ### أنشئ_مسلكا (createThread) +
+ ``` دالة أنشئ_مسلكا( مسلك: مؤشر[مـسلك]، @@ -38,7 +39,7 @@ Apm.importPackage("Alusus/Threading@0.1"); ): صـحيح؛ ``` -
+
``` func createThread( @@ -49,8 +50,6 @@ Apm.importPackage("Alusus/Threading@0.1"); ): Int; ``` -
- دالة لإنشاء مسلك. تطابق هذه الدالة دالة `pthread_create` من Posix. المعطيات: @@ -69,18 +68,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### التق_بمسلك (joinThread) +
+ ``` دالة التق_بمسلك(مسلك: مؤشر[مـسلك]، نتيجة: مؤشر[مؤشر]): صـحيح؛ ``` -
+
``` func joinThread(pthread: ptr[Thread], retval: ptr[ptr]): Int; ``` -
- تنتظر مسلكا حتى يكتمل تنفيذه وتستلم منه القيمة المرجعة من دالة المسلك. هذه الدالة تطابق دالة `pthread_join` من Posix. المعطيات: @@ -95,18 +94,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### هيئ_مزامنا (initMutex) +
+ ``` دالة هيئ_مزامنا(مزامن: مؤشر[مـزامن]، مزايا: مؤشر[مـزايا_مزامن]): صـحيح؛ ``` -
+
``` func initMutex(mutex: ptr[Mutex], attrs: ptr[MutexAttributes]): Int; ``` -
- تهيئ مزامنا. يجب تهيئة المزامن باستخدام هذه الدالة قبل التمكن من استخدامه. هذه الدالة تطابق دالة `pthread_mutex_init` من Posix. @@ -122,18 +121,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### اقفل_مزامنا (lockMutex) +
+ ``` دالة اقفل_مزامنا(مزامن: مؤشر[مـزامن]): صـحيح؛ ``` -
+
``` func lockMutex(mutex: ptr[Mutex]): Int; ``` -
- تقفل المزامن وتحجزه للمسلك الحالي. إن كان المزامن محجوزا من قبل مسلك آخر فسيُجمد هذا المسلك حتى يتم تحرير المزامن من قبل المسلك الآخر. هذه الدالة تطابق دالة `pthread_mutex_lock` من Posix. @@ -147,18 +146,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### حاول_قفل_مزامن (tryLockMutex) +
+ ``` دالة حاول_قفل_مزامن(مزامن: مؤشر[مـزامن]): صـحيح؛ ``` -
+
``` func tryLockMutex(mutex: ptr[Mutex]): Int; ``` -
- تقفل المزامن إذا كان حرًا، وتُرجع رمز خطأ مباشرة دون انتظار إذا كان المزامن محجوزًا من قبل مسلك آخر. هذه الدالة تطابق دالة `pthread_mutex_trylock` من Posix. @@ -172,18 +171,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### افتح_مزامنا (unlockMutex) +
+ ``` دالة افتح_مزامنا(مزامن: مؤشر[مـزامن]): صـحيح؛ ``` -
+
``` func unlockMutex(mutex: ptr[Mutex]): Int; ``` -
- تحرر مزامنًا وتجعله متوفرًا للمسالك الأخرى. هذه الدالة تطابق دالة `pthread_mutex_unlock` من Posix. المعطيات: @@ -196,18 +195,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### هيئ_شرطا (initCond) +
+ ``` دالة هيئ_شرطا(شرط: مؤشر[شـرط]، مزايا: مؤشر[مـزايا_شرط]): صـحيح؛ ``` -
+
``` func initCond(cond: ptr[Cond], attrs: ptr[CondAttributes]): Int; ``` -
- يهيئ كائنا من صنف `شـرط`. يجب تهيئة الشرط بهذه الدالة قبل استخدامه. هذه الدالة تطابق دالة `pthread_cond_init` من Posix. @@ -223,18 +222,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### علم_شرطا (signalCond) +
+ ``` دالة علم_شرطا(شرط: مؤشر[شـرط]): صـحيح؛ ``` -
+
``` func signalCond(cond: ptr[Cond]): Int; ``` -
- يُرسل إشارة بأن الشرط المعني قد تحقق. يؤدي ذلك لتحرير مسلك واحد من المسالك المنتظرة لهذا الشرط. إن وُجد عدة مسالك تنتظر الشرط فسيُحرر واحد منها فقط لكل استدعاء لهذه الدالة. قبل استدعاء هذه الدالة يجب على المسلك قفل مزامن (نفس المزامن المستخدم من قبل المسالك التي تستدعي `انتظر_شرطا` `waitCond`) ويجب تحرير @@ -252,18 +251,18 @@ Apm.importPackage("Alusus/Threading@0.1"); ### انتظر_شرطا (waitCond) +
+ ``` دالة انتظر_شرطا(شرط: مؤشر[شـرط]، مزامن: مؤشر[مـزامن]): صـحيح؛ ``` -
+
``` func waitCond(cond: ptr[Cond], mutex: ptr[Mutex]): Int; ``` -
- تنتظر تحقق شرط. تستقبل هذه الدالة مزامنا بالإضافة إلى الشرط المعني وتتطلب أن يكون المزامن مقفلًا قبل استداءها. تعمل الدالة بشكل لا انشطاري (atomic) على تجميد المسلك وتحرير المزامن. عند تحقق الشرط تقوم الدالة بشكل لا انشطاري بقفل المزامن مجددًا وتحرير المسلك. @@ -279,11 +278,12 @@ Apm.importPackage("Alusus/Threading@0.1"); تُرجع الدالة 0 في حالة نجاح العملية، ورمز خطئ في حالة فشلها. - ## الأصناف ### مـزايا_مسلك (ThreadAttributes) +
+ ``` صنف مـزايا_مسلك { عرف أعلام: صـحيح؛ @@ -299,7 +299,7 @@ Apm.importPackage("Alusus/Threading@0.1"); } ``` -
+
``` class ThreadAttributes { @@ -316,157 +316,157 @@ class ThreadAttributes { } ``` -
- #### أعلام (flags) +
+ ``` عرف أعلام: صـحيح؛ ``` -
+
``` def flags: Int; ``` -
- #### حجم_المكدس (stackSize) +
+ ``` عرف حجم_المكدس: صـحيح؛ ``` -
+
``` def stackSize: Int; ``` -
- #### مجال_التنافس (contentionScope) +
+ ``` عرف مجال_التنافس: صـحيح؛ ``` -
+
``` def contentionScope: Int; ``` -
- #### توريث_الجدولة (inheritSched) +
+ ``` عرف توريث_الجدولة: صـحيح؛ ``` -
+
``` def inheritSched: Int; ``` -
- #### فصل_الحالة (detachState) +
+ ``` عرف فصل_الحالة: صـحيح؛ ``` -
+
``` def detachState: Int; ``` -
- #### جدولة (sched) +
+ ``` عرف جدولة: صـحيح؛ ``` -
+
``` def sched: Int; ``` -
- #### معلمة (param) +
+ ``` عرف معلمة: مـعامل_جدولة؛ ``` -
+
``` def param: SchedParam; ``` -
- #### وقت_البداية (startTime) +
+ ``` عرف وقت_البداية: تـفصيل_زمني؛ ``` -
+
``` def startTime: TimeSpec; ``` -
- #### حد_اقصى (deadLine) +
+ ``` عرف حد_اقصى: تـفصيل_زمني؛ ``` -
+
``` def deadLine: TimeSpec; ``` -
- #### فترة (period) +
+ ``` عرف فترة: تـفصيل_زمني؛ ``` -
+
``` def period: TimeSpec; ``` -
- ### مـعامل_جدولة (SchedParam) +
+ ``` صنف مـعامل_جدولة { عرف أولوية_الجدولة: صـحيح؛ } ``` -
+
``` class SchedParam { @@ -474,24 +474,24 @@ class SchedParam { } ``` -
- #### أولوية_الجدولة (schedPriority) +
+ ``` عرف أولوية_الجدولة: صـحيح؛ ``` -
+
``` def schedPriority: Int; ``` -
- ### تـفصيل_زمني (TimeSpec) +
+ ``` صنف تـفصيل_زمني { عرف مدة_ثواني: صـحيح_متكيف؛ @@ -499,7 +499,7 @@ def schedPriority: Int; } ``` -
+
``` class TimeSpec { @@ -508,71 +508,112 @@ class TimeSpec { } ``` -
- #### مدة_ثواني (tvSec) +
+ ``` عرف مدة_ثواني: صـحيح_متكيف؛ ``` -
+
``` def tvSec: ArchInt; ``` -
- #### مدة_نانو (tvNsec) +
+ ``` عرف مدة_نانو: صـحيح[64]؛ ``` - -
+
``` def tvNsec: Int[64]; ``` +### مـزامن (Mutex) + +
+ +``` +صنف مـزامن { + عملية هذا.هيئ(); + عملية هذا.هيئ(مزايا : سند[مـزايا_مزامن]); + عملية هذا.اقفل(); + عملية هذا.افتح(); +} +``` +
-### مـزامن (Mutex) +``` +class Mutex { + handler this.init(); + handler this.init(attrs: ref[MutexAttributes]); + handler this.lock(); + handler this.unlock() +} +``` يستخدم للمزامنة بين المسالك المختلفة ويتم ذلك بطلب المسلك قفل المزامن، ومن ثم بعد الحصول على القفل يقوم بالعمل المراد ثم يحرر القفل ليتسنى لمسلك آخر قفله. #### هيئ (init) +
+ ``` عملية هذا.هيئ()؛ عملية هذا.هيئ(مزايا: سند[مـزايا_مزامن])؛ ``` -
+
``` handler this.init() handler this.init(attr: ref[MutexAttributes]) ``` -
- دالة لتهيئة المزامن. يجب استدعاء هذه الدالة قبل استخدام المزامن. #### اقفل (lock) +
+ +``` +عملية هذا.اقفل(); +``` + +
+ +``` +handler this.lock(); +``` + تستخدم لقفل المزامن ولا تستلم أي معطيات. عند استدعاء هذه الدالة يُلبث المسلك لحين تحرر هذا المزامن من أي قفل. #### افتح (unlock) +
+ +``` +عملية هذا.افتح(); +``` + +
+ +``` +handler this.unlock(); +``` + تفتح القفل ما يتيح لنظام التشغيل تحرير أحد المسالك المُنتظِرة لهذا القفل. ### مـزايا_مزامن (MutexAttributes) -
- ``` class MutexAttributes { def pshared: Int = 0; @@ -582,70 +623,44 @@ class MutexAttributes { } ``` -
- #### pshared -
- ``` def pshared: Int; ``` -
- #### kind -
- ``` def kind: Int; ``` -
- #### protocol -
- ``` def protocol: Int; ``` -
- #### robustness -
- ``` def robustness: Int; ``` -
- ### مـزايا_شرط (CondAttributes) -
- ``` class CondAttributes { def dummy: Int = 0; } ``` -
- #### dummy -
- ``` def dummy: Int; ``` -
- ### مـحلي_لمسلك (ThreadLocal) قالب أصناف يستخدم لإنشاء متغيرات محلية نسبة إلى مسلك، أي عمومية ضمن مسلك معين لكنها لا تُشارك مع @@ -662,6 +677,8 @@ def dummy: Int; المثال التالي يوضح استخدام هذا القالب: +
+ ``` عرف متغير: تـوازي.مـحلي_لمسلك[صـنفي](مغلفة(م: سند[صـنفي]) { م.ع = ريـاضيات.عشوائي()؛ @@ -671,7 +688,7 @@ def dummy: Int; طـرفية.اطبع(متغير.القيمة.ع)؛ ``` -
+
``` def var: Threading.ThreadLocal[MyType](closure (val: ref[A]) { @@ -682,14 +699,13 @@ def var: Threading.ThreadLocal[MyType](closure (val: ref[A]) { Console.print(var.value.i); ``` -
- في هذا المثال نعرف `متغير` (`var`) ليحتوي على قيمة من صنف `صـنفي` (`MyType`) وعند إنشاء المتغير ذو الصنف `صـنفي` ضمن مسلك معين تُحدد قيمة الخصلة `ع` (`i`) منه بقيمة عشوائية. - ## مثال +
+ ``` اشمل "مـتم/طـرفية"؛ اشمل "مـحا"؛ @@ -747,7 +763,7 @@ Console.print(var.value.i); مجموع_كلي(); ``` -
+
``` import "Srl/Console"; @@ -807,12 +823,6 @@ func calculateSum(p: ptr): ptr { totalSum(); ``` -
- ---- - ## الرخصة هذا المشروع مرخص بموجب رخصة غنو العمومية الصغرى الإصدار 3.0 (LGPL-3.0). راجع ملفات `COPYING` و `COPYING.LESSER` للحصول على التفاصيل. - -
diff --git a/README.md b/README.md index 6aa4792..dde8975 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,11 @@ # Threading + [[عربي]](README.ar.md) Provides threading and thread synchronization functionality. ## Adding to the Project - - Use the following lines: ``` @@ -16,13 +15,17 @@ Apm.importPackage("Alusus/Threading@0.1"); ## Functions - - ### createThread ``` -func createThread(pthread: ptr[Thread], attr: ptr[ThreadAttributes], startRoutine: ptr[func (ptr): ptr], arg: ptr): Int + func createThread( + pthread: ptr[Thread], + attr: ptr[ThreadAttributes], + startRoutine: ptr[func (ptr): ptr], + arg: ptr + ): Int; ``` + Create a thread. This function is equivalent to Posix `pthread_create`. Returns 0 on success, an error code otherwise. * `pthread`: A pointer to a variable of type Thread, in which the result is stored. @@ -35,6 +38,7 @@ Create a thread. This function is equivalent to Posix `pthread_create`. Returns ``` func joinThread(pthread: ptr[Thread], retval: ptr[ptr]): Int ``` + Waits for a thread to finish execution. This function is equivalent to Posix `pthread_join`. Returns 0 on success, an error code otherwise. * `pthread`: A pointer to the thread to wait for. @@ -45,6 +49,7 @@ Waits for a thread to finish execution. This function is equivalent to Posix `pt ``` func initMutex(mutex: ptr[Mutex], attrs: ptr[MutexAttributes]): Int ``` + Initializes a mutex lock. A mutex must be initialized by this function before it can be used. This function is equivalent to Posix `pthread_mutex_init`. Returns 0 on success, an error code otherwise. * `mutex`: A pointer to the Mutex object. @@ -55,6 +60,7 @@ Initializes a mutex lock. A mutex must be initialized by this function before it ``` func lockMutex(mutex: ptr[Mutex]): Int ``` + Locks the mutex object. If the mutex is locked by another thread the current thread will be paused until the mutex is available. This function is equivalent to Posix `pthread_mutex_lock`. Returns 0 on success, an error code otherwise. * `mutex`: A pointer to the Mutex object. @@ -64,6 +70,7 @@ Locks the mutex object. If the mutex is locked by another thread the current thr ``` func tryLockMutex(mutex: ptr[Mutex]): Int ``` + Locks the mutex object. If the mutex is locked by another thread the function returns immediately with an error code. This function is equivalent to Posix `pthread_mutex_trylock`. Returns 0 on success, an error code otherwise. * `mutex`: A pointer to the Mutex object. @@ -73,6 +80,7 @@ Locks the mutex object. If the mutex is locked by another thread the function re ``` func unlockMutex(mutex: ptr[Mutex]): Int ``` + Unlocks a mutex. This function is equivalent to Posix `pthread_mutex_unlock`. Returns 0 on success, an error code otherwise. * `mutex`: A pointer to the Mutex object. @@ -82,6 +90,7 @@ Unlocks a mutex. This function is equivalent to Posix `pthread_mutex_unlock`. Re ``` func initCond(cond: ptr[Cond], attrs: ptr[CondAttributes]): Int ``` + Initializes a condition object. A condition must be initialized by this function before it can be used. This function is equivalent to Posix `pthread_cond_init`. Returns 0 on success, an error code otherwise. * `cond`: A pointer to the Cond object. @@ -92,6 +101,7 @@ Initializes a condition object. A condition must be initialized by this function ``` func signalCond(cond: ptr[Cond]): Int ``` + Sends a signal that a condition is met. This will unlock one thread that is waiting on this condition. If multiple threads are waiting for the same condition only one of them will be released per call. Before calling this function the calling thread must first lock a mutex (the same mutex used by the thread in `waitCond`) and must release the mutex after the call. The thread calling `waitCond` will only be released after the mutex is released since the `waitCond` will attempt to lock the mutex before returning. This is equivalent to Posix `pthread_cond_signal`. Returns 0 on success, an error code otherwise. * `cond`: A pointer to the condition object to signal. @@ -101,6 +111,7 @@ Sends a signal that a condition is met. This will unlock one thread that is wait ``` func waitCond(cond: ptr[Cond], mutex: ptr[Mutex]): Int ``` + Waits for a condition to be met. This takes a mutex in addition to the condition to wait for, and it requires that the mutex is locked before the call. The function will atomically block the thread and release the mutex. When the condition is signaled the function will atomically re-lock the mutex and release the calling thread. This function is equivalent to Posix `pthread_cond_wait`. Returns 0 on success, an error code otherwise. * `cond`: A pointer to the Cond object to wait on. @@ -220,9 +231,17 @@ def tvSec: ArchInt; def tvNsec: Int[64]; ``` - ### Mutex +``` +class Mutex { + handler this.init(); + handler this.init(attrs: ref[MutexAttributes]); + handler this.lock(); + handler this.unlock() +} +``` + Used for synchronizing threads by allowing threads to request locking the mutex and release the lock after the thread is done with the synchronized work. @@ -232,14 +251,23 @@ lock after the thread is done with the synchronized work. handler this.init() handler this.init(attr: ref[MutexAttributes]) ``` + Initializes the mutex. This must be called before the mutex is usable. #### lock +``` +handler this.lock(); +``` + Locks the mutex. This will freeze the thread until the lock is available. #### unlock +``` +handler this.unlock(); +``` + Unlocks the mutex allowing the OS to release another waiting thread. ### MutexAttributes @@ -291,8 +319,6 @@ class CondAttributes { def dummy: Int; ``` - - ### ThreadLocal Type template used to define thread local variables, i.e. variables that are global within a @@ -323,8 +349,6 @@ In this example `var` is declared to contain a value of type `MyType`. When the ## Example - - ``` import "Srl/Console"; import "Apm"; @@ -385,6 +409,4 @@ totalSum(); ## License - - -This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the `COPYING` and `COPYING.LESSER` files for details. +This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the `COPYING` and `COPYING.LESSER` files for details. \ No newline at end of file