godot/doc/classes/Semaphore.xml

<?xml version="1.0" encoding="UTF-8" ?>
<class name="Semaphore" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
	<brief_description>
		A synchronization mechanism used to control access to a shared resource by [Thread]s.
	</brief_description>
	<description>
		A synchronization semaphore that can be used to synchronize multiple [Thread]s. Initialized to zero on creation. For a binary version, see [Mutex].
		[b]Warning:[/b] Semaphores must be used carefully to avoid deadlocks.
		[b]Warning:[/b] To guarantee that the operating system is able to perform proper cleanup (no crashes, no deadlocks), these conditions must be met:
		- When a [Semaphore]'s reference count reaches zero and it is therefore destroyed, no threads must be waiting on it.
		- When a [Thread]'s reference count reaches zero and it is therefore destroyed, it must not be waiting on any semaphore.
	</description>
	<tutorials>
		<link title="Using multiple threads">$DOCS_URL/tutorials/performance/using_multiple_threads.html</link>
		<link title="Thread-safe APIs">$DOCS_URL/tutorials/performance/thread_safe_apis.html</link>
	</tutorials>
	<methods>
		<method name="post">
			<return type="void" />
			<description>
				Lowers the [Semaphore], allowing one more thread in.
			</description>
		</method>
		<method name="try_wait">
			<return type="bool" />
			<description>
				Like [method wait], but won't block, so if the value is zero, fails immediately and returns [code]false[/code]. If non-zero, it returns [code]true[/code] to report success.
			</description>
		</method>
		<method name="wait">
			<return type="void" />
			<description>
				Waits for the [Semaphore], if its value is zero, blocks until non-zero.
			</description>
		</method>
	</methods>
</class>
Changed the doc class generation to individual files per class. It is also possible to save module files in module directories and the build system will recognize them. 2017-09-13 04:42:36 +08:00			`<?xml version="1.0" encoding="UTF-8" ?>`
Doctool: Remove version attribute from XML header We don't use that info for anything, and it generates unnecessary diffs every time we bump the minor version (and CI failures if we forget to sync some files from opt-in modules (mono, text_server_fb). 2023-07-06 16:08:05 +08:00			`<class name="Semaphore" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">`
Changed the doc class generation to individual files per class. It is also possible to save module files in module directories and the build system will recognize them. 2017-09-13 04:42:36 +08:00			`<brief_description>`
Overhaul the top sections of the class reference (Core classes) 2023-04-28 07:35:33 +08:00			`A synchronization mechanism used to control access to a shared resource by [Thread]s.`
Changed the doc class generation to individual files per class. It is also possible to save module files in module directories and the build system will recognize them. 2017-09-13 04:42:36 +08:00			`</brief_description>`
			`<description>`
Overhaul the top sections of the class reference (Core classes) 2023-04-28 07:35:33 +08:00			`A synchronization semaphore that can be used to synchronize multiple [Thread]s. Initialized to zero on creation. For a binary version, see [Mutex].`
			`[b]Warning:[/b] Semaphores must be used carefully to avoid deadlocks.`
			`[b]Warning:[/b] To guarantee that the operating system is able to perform proper cleanup (no crashes, no deadlocks), these conditions must be met:`
			`- When a [Semaphore]'s reference count reaches zero and it is therefore destroyed, no threads must be waiting on it.`
			`- When a [Thread]'s reference count reaches zero and it is therefore destroyed, it must not be waiting on any semaphore.`
Changed the doc class generation to individual files per class. It is also possible to save module files in module directories and the build system will recognize them. 2017-09-13 04:42:36 +08:00			`</description>`
			`<tutorials>`
Replace Godot docs URL with `$DOCS_URL` in XML class reference 2021-11-15 17:43:07 +08:00			`<link title="Using multiple threads">$DOCS_URL/tutorials/performance/using_multiple_threads.html</link>`
Overhaul the top sections of the class reference (Core classes) 2023-04-28 07:35:33 +08:00			`<link title="Thread-safe APIs">$DOCS_URL/tutorials/performance/thread_safe_apis.html</link>`
Changed the doc class generation to individual files per class. It is also possible to save module files in module directories and the build system will recognize them. 2017-09-13 04:42:36 +08:00			`</tutorials>`
			`<methods>`
			`<method name="post">`
doc: Use self-closing tags for `return` and `argument` For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there. 2021-07-30 21:28:05 +08:00			`<return type="void" />`
Changed the doc class generation to individual files per class. It is also possible to save module files in module directories and the build system will recognize them. 2017-09-13 04:42:36 +08:00			`<description>`
Drop old semaphore implementation - Removed platform-specific implementations. - Now all semaphores are in-object, unless they need to be conditionally created. - Similarly to `Mutex`, provided a dummy implementation for when `NO_THREADS` is defined. - Similarly to `Mutex`, methods are made `const` for easy use in such contexts. - Language bindings updated: `wait()` and `post()` are now `void`. - Language bindings updated: `try_wait()` added. Bonus: - Rewritten the `#ifdef` in `mutex.h` to meet the code style. 2020-03-03 16:26:42 +08:00			`Lowers the [Semaphore], allowing one more thread in.`
Changed the doc class generation to individual files per class. It is also possible to save module files in module directories and the build system will recognize them. 2017-09-13 04:42:36 +08:00			`</description>`
			`</method>`
doc: Sync classref with current source 2020-03-09 17:12:53 +08:00			`<method name="try_wait">`
Booleanize various sync primitives' wait & locking methods 2023-01-27 18:04:41 +08:00			`<return type="bool" />`
Drop old semaphore implementation - Removed platform-specific implementations. - Now all semaphores are in-object, unless they need to be conditionally created. - Similarly to `Mutex`, provided a dummy implementation for when `NO_THREADS` is defined. - Similarly to `Mutex`, methods are made `const` for easy use in such contexts. - Language bindings updated: `wait()` and `post()` are now `void`. - Language bindings updated: `try_wait()` added. Bonus: - Rewritten the `#ifdef` in `mutex.h` to meet the code style. 2020-03-03 16:26:42 +08:00			`<description>`
Booleanize various sync primitives' wait & locking methods 2023-01-27 18:04:41 +08:00			`Like [method wait], but won't block, so if the value is zero, fails immediately and returns [code]false[/code]. If non-zero, it returns [code]true[/code] to report success.`
Drop old semaphore implementation - Removed platform-specific implementations. - Now all semaphores are in-object, unless they need to be conditionally created. - Similarly to `Mutex`, provided a dummy implementation for when `NO_THREADS` is defined. - Similarly to `Mutex`, methods are made `const` for easy use in such contexts. - Language bindings updated: `wait()` and `post()` are now `void`. - Language bindings updated: `try_wait()` added. Bonus: - Rewritten the `#ifdef` in `mutex.h` to meet the code style. 2020-03-03 16:26:42 +08:00			`</description>`
			`</method>`
doc: Sync classref with current source 2020-03-09 17:12:53 +08:00			`<method name="wait">`
doc: Use self-closing tags for `return` and `argument` For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there. 2021-07-30 21:28:05 +08:00			`<return type="void" />`
Changed the doc class generation to individual files per class. It is also possible to save module files in module directories and the build system will recognize them. 2017-09-13 04:42:36 +08:00			`<description>`
doc: Sync classref with current source 2020-03-09 17:12:53 +08:00			`Waits for the [Semaphore], if its value is zero, blocks until non-zero.`
Changed the doc class generation to individual files per class. It is also possible to save module files in module directories and the build system will recognize them. 2017-09-13 04:42:36 +08:00			`</description>`
			`</method>`
			`</methods>`
			`</class>`