Merge pull request #60502 from timothyqiu/sem-api

core/bind/core_bind.cpp

@@ -2613,6 +2613,10 @@ Error _Semaphore::wait() {
 	return OK; // Can't fail anymore; keep compat
 }
 
+Error _Semaphore::try_wait() {
+	return semaphore.try_wait() ? OK : ERR_BUSY;
+}
+
 Error _Semaphore::post() {
 	semaphore.post();
 	return OK; // Can't fail anymore; keep compat
@@ -2621,6 +2625,7 @@ Error _Semaphore::post() {
 void _Semaphore::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("wait"), &_Semaphore::wait);
 	ClassDB::bind_method(D_METHOD("post"), &_Semaphore::post);
+	ClassDB::bind_method(D_METHOD("try_wait"), &_Semaphore::try_wait);
 }
 
 ///////////////

core/bind/core_bind.h

@@ -680,6 +680,7 @@ class _Semaphore : public Reference {
 
 public:
 	Error wait();
+	Error try_wait();
 	Error post();
 };
 

doc/classes/Semaphore.xml

@@ -13,13 +13,21 @@
 		<method name="post">
 			<return type="int" enum="Error" />
 			<description>
-				Lowers the [Semaphore], allowing one more thread in. Returns [constant OK] on success, [constant ERR_BUSY] otherwise.
+				Lowers the [Semaphore], allowing one more thread in.
+				[b]Note:[/b] This method internals' can't possibly fail, but an error code is returned for backwards compatibility, which will always be [constant OK].
+			</description>
+		</method>
+		<method name="try_wait">
+			<return type="int" enum="Error" />
+			<description>
+				Like [method wait], but won't block, so if the value is zero, fails immediately and returns [constant ERR_BUSY]. If non-zero, it returns [constant OK] to report success.
 			</description>
 		</method>
 		<method name="wait">
 			<return type="int" enum="Error" />
 			<description>
-				Tries to wait for the [Semaphore], if its value is zero, blocks until non-zero. Returns [constant OK] on success, [constant ERR_BUSY] otherwise.
+				Waits for the [Semaphore], if its value is zero, blocks until non-zero.
+				[b]Note:[/b] This method internals' can't possibly fail, but an error code is returned for backwards compatibility, which will always be [constant OK].
 			</description>
 		</method>
 	</methods>