Handles (SourceMod Scripting) - Revision history

MAGNAT2645: DBDrivers are not closeable

2020-12-17T13:17:24Z

DBDrivers are not closeable

DJ Tsunami: /* Cloning Handles */

2020-08-15T08:41:41Z

‎Cloning Handles

DJ Tsunami: /* When to close */

2020-08-15T08:35:18Z

‎When to close

XXDeathreusXx: /* When to close */

2020-08-15T04:10:32Z

‎When to close

Joinedsenses: Update highlighting

2020-03-30T00:02:12Z

Update highlighting

Joinedsenses: /* When to close */ Update Handle to DirectoryListing

2020-03-30T00:01:30Z

‎When to close: Update Handle to DirectoryListing

Headline: /* Handle Types */

2017-09-28T21:48:46Z

‎Handle Types

Headline: /* When to close */

2017-09-28T21:47:03Z

‎When to close

Headline: /* When to close */

2017-09-28T21:46:48Z

‎When to close

Abrandnewday: Updating instances of CloseHandle to the delete operator. Also, is the double-space after a period a formatting "thing" that articles should follow?

2017-03-31T03:11:12Z

Updating instances of CloseHandle to the delete operator. Also, is the double-space after a period a formatting "thing" that articles should follow?

@@ Line 137: / Line 137: @@
 ==Database Drivers==
-{{HandleType|DBDriver|Yes|No|Core|dbi.inc}}
+{{HandleType|DBDriver|No|No|Core|dbi.inc}}
 DBDriver Handles contain information about a database driver.  They are static and cannot be closed.

@@ Line 72: / Line 72: @@
 There are two ways of cloning.  A plugin can either clone a Handle itself, and become the owner, or it can explicitly set a new owner.  The difference is one of API design.  Example of the former:
-<sourcepawn>DataBase g_hSQL;
+<sourcepawn>Database g_hSQL;
 /**
   * The other plugin calling this function must pass his ID in,
@@ Line 79: / Line 79: @@
 public Database GetGlobalSQL(Handle otherPlugin)
+{
-    return view_as<DataBase>(CloneHandle(g_hSQL, otherPlugin));
+    return view_as<Database>(CloneHandle(g_hSQL, otherPlugin));
+}
@@ Line 85: / Line 85: @@
   * This code would appear in the other plugin
   */
-DataBase sql = GetGlobalSQL(myself);
+Database sql = GetGlobalSQL(myself);
 /* ... */
 delete sql;
@@ Line 91: / Line 91: @@
 Example of the latter:
-<sourcepawn>DataBase g_hSQL;
+<sourcepawn>Database g_hSQL;
 /**
   * The calling plugin must call CloneHandle() himself.
   */
-public DataBase GetGlobalSQL()
+public Database GetGlobalSQL()
+{
     return g_hSQL;
@@ Line 103: / Line 103: @@
   * This code would appear in the other plugin
   */
-DataBase sql = GetGlobalSQL();
+Database sql = GetGlobalSQL();
-if (sql != INVALID_HANDLE)
+if (sql != null)
+{
-    sql = view_as<DataBase>(CloneHandle(sql));
+    sql = view_as<Database>(CloneHandle(sql));
+}
 delete sql;

@@ Line 31: / Line 31: @@
+   }
-   while (ReadDirEntry(dir, path, sizeof(path), type))
+   while (dir.GetNext(path, sizeof(path), type))
+   {
      if (type == FileType_File && StrEqual(path, file))

@@ Line 35: / Line 35: @@
      if (type == FileType_File && StrEqual(path, file))
+     {
        return true;
+     }

@@ Line 10: / Line 10: @@
 Opening a Handle is usually done implicitly by a native function.  For example, OpenDirectory opens a new Handle which is used in other Directory natives.  This associates a ''type'' with the Handle.  Trying to use a Directory Handle with any other non-Directory native will cause an error (HandleError_Type), because Handles are type checked.
-<pawn>Handle hndl = OpenDirectory("addons/sourcemod/configs");
+<sourcepawn>Handle hndl = OpenDirectory("addons/sourcemod/configs");
-</pawn>
+</sourcepawn>
 =Closing Handles=
@@ Line 20: / Line 20: @@
 When a plugin unloads, all of its Handles are automatically destroyed.  This does not mean, however, that closing Handles is optional.  Consider the following code:
-<pawn>bool IsFileInFolder(const char[] path, const char[] file)
+<sourcepawn>bool IsFileInFolder(const char[] path, const char[] file)
+{
-	char path[PLATFORM_MAX_PATH];
+  char path[PLATFORM_MAX_PATH];
-	FileType type;
+  FileType type;
-	DirectoryListing dir = OpenDirectory(path);
+  DirectoryListing dir = OpenDirectory(path);
-	if (dir == null)
+  if (dir == null)
-−
+  {
-		return false;
+    return false;
-−
+  }
-	while (ReadDirEntry(dir, path, sizeof(path), type))
+  while (ReadDirEntry(dir, path, sizeof(path), type))
-−
+  {
-		if (type == FileType_File && StrEqual(path, file))
+    if (type == FileType_File && StrEqual(path, file))
-−
+    {
-			return true;
+      return true;
-−
+    }
-−
+  }
-	delete dir;
+  delete dir;
-	return false;
+  return false;
+}
-</pawn>
+</sourcepawn>
 This function searches a directory for a single file.  If this function were to not close the handle with the <tt>delete</tt> operator, it would [[Memory Leak|leak memory]] every time it was called, and eventually the script would fill up with a large number of lingering Handles that were left open.
@@ Line 71: / Line 71: @@
 There are two ways of cloning.  A plugin can either clone a Handle itself, and become the owner, or it can explicitly set a new owner.  The difference is one of API design.  Example of the former:
-<pawn>DataBase g_hSQL;
+<sourcepawn>DataBase g_hSQL;
 /**
   * The other plugin calling this function must pass his ID in,
@@ Line 87: / Line 87: @@
 /* ... */
 delete sql;
-</pawn>
+</sourcepawn>
 Example of the latter:
-<pawn>DataBase g_hSQL;
+<sourcepawn>DataBase g_hSQL;
 /**
   * The calling plugin must call CloneHandle() himself.
@@ Line 108: / Line 108: @@
+}
 delete sql;
-</pawn>
+</sourcepawn>
 =Handle Types=

@@ Line 111: / Line 111: @@
 =Handle Types=
-The following is a list of some common Handle types provided by SourceMod and some documentation on each.  Some Handles are exposed, by name, so that Extensions can create Handles of this type.  An example:
+The following is a list of some common Handle types provided by SourceMod and some documentation on each.
 ==BitBuffers==

@@ Line 26: / Line 26: @@
 	Handle dir = OpenDirectory(path);
-	if (dir == nukk)
+	if (dir == null)
+	{
 		return false;

@@ Line 15: / Line 15: @@
 =Closing Handles=
 ==Basic operation==
-Closing a Handle means seeing if the internal object can be removed from memory.  For example, if a plugin creates an SQL connection, closing the Handle means closing and destroying the connection.  This is almost always done using the CloseHandle() native function.
+Closing a Handle means seeing if the internal object can be removed from memory.  For example, if a plugin creates an SQL connection, closing the Handle means closing and destroying the connection. This is almost always done using the <tt>delete</tt> operator and specifying the handle to close, e.g. <tt>delete hDir;</tt>
 ==When to close==
@@ Line 45: / Line 45: @@
 </pawn>
-This function searches a directory for a single file.  If this function were to omit the call to CloseHandle, it would [[Memory Leak|leak memory]] every time it was called, and eventually the script would fill up with a large number of lingering Handles that were left open.
+This function searches a directory for a single file.  If this function were to not close the handle with the <tt>delete</tt> operator, it would [[Memory Leak|leak memory]] every time it was called, and eventually the script would fill up with a large number of lingering Handles that were left open.
 So, when do you close Handles?  There are generally two rules of thumb to go by:
@@ Line 68: / Line 68: @@
 *Plugin 'B' tries to use the Handle.
-To prevent this, the CloneHandle native is provided.  This function returns a ''new'' Handle that is a "copy" of the original.  While their values won't be equal, they contain the same internal data.  The data itself will not be destroyed until each copy and the original are closed with CloseHandle.  It does not matter what order they are freed in, however, each Handle can only be freed once.
+To prevent this, the CloneHandle native is provided.  This function returns a ''new'' Handle that is a "copy" of the original.  While their values won't be equal, they contain the same internal data.  The data itself will not be destroyed until each copy and the original are closed with the <tt>delete</tt> operator.  It does not matter what order they are freed in, however, each Handle can only be freed once.
 There are two ways of cloning.  A plugin can either clone a Handle itself, and become the owner, or it can explicitly set a new owner.  The difference is one of API design.  Example of the former:
@@ Line 203: / Line 203: @@
 *The timer ends (via Plugin_Stop or being a one-time timer that is finished)
 *The timer is killed via <tt>KillTimer</tt>
-*The timer is closed via <tt>CloseHandle</tt>
+*The timer is closed via <tt>delete hHandle;</tt>
 *The timer's parent plugin unloads
 [[Category:SourceMod Scripting]]