Skip to content

全局变量

PySpigot 包含一个全局变量系统，在运行时可以被脚本访问。在 Java 端，这个系统依赖于一个HashMap，它是一种数据结构，类似于 Python 中的字典，以键值对的方式存储数据。该系统的目的是允许脚本之间共享变量。如果你正在编写一个需要依赖其他脚本信息才能正确运行的脚本系统，这个功能可能会很有用。

向全局变量集中插入的变量发生更改后，所有脚本都会自动看到这些更改。如果变量的值发生了改变，就无需重新将其插入全局变量集。

访问全局变量系统

PySpigot 的全局变量系统可以像访问 PySpigot 的任何管理器一样访问。有三种访问方式：

通过 pyspigot 辅助模块

1
2
3
4
5
import pyspigot as ps

global_vars = ps.global_variables()

global_vars.<function>

pyspigot 辅助模块还定义了一些常见的别名以方便使用。ps.global_vars 和 ps.gv 都可以使用。例如：

1
2
3
4
import pyspigot as ps

ps.global_vars.<function>
ps.gv.<function>

通过 PySpigot 类

1
2
3
4
5
from dev.magicmq.pyspigot import PySpigot as ps

global_vars = ps.global_vars

global_vars.<function>

直接导入

1
2
3
from dev.magicmq.pyspigot.manager.script import GlobalVariables as global_vars

global_vars.get().<function>
警告

如果通过直接导入访问全局变量系统，必须调用 get()！

用法

基本使用全局变量系统涉及调用 set、get 和 remove 函数。请参阅下面更详细的这些函数描述。以下是一个简短的示例：

1
2
3
4
5
6
7
import pyspigot as ps

global_vars = ps.global_variables()# (1)!

test = 'Global variable'

global_vars.set('test', test)# (2)!
  1. 在这一行，全局变量系统从 pyspigot 辅助模块中获取。
  2. 在这一行，使用键值"test"将一个新值设定到全局变量系统中，并赋予变量test的值("Global variable")。
1
2
3
4
5
6
7
8
9
import pyspigot as ps

global_vars = ps.global_variables()# (1)!

test = global_vars.get('test')# (2)!

print(test)

global_vars.remove('test')# (3)!
  1. 在这一行，全局变量系统从 pyspigot 辅助模块中获取。
  2. 在这一行，获取键值"test"对应的值。此值是之前在脚本 A 中设置的。
  3. 在获取完变量后，使用 remove 函数将其删除，传入应删除的键。在使用完后移除变量非常重要，以避免内存泄漏。有关更多信息，请参阅下面的避免内存泄漏部分。

在上述代码中，在脚本 A 中设置了全局变量系统中的变量 test。然后，在脚本 B 中检索和打印了 test 的值，然后在检索后移除了该变量。

Warning

键/名称是唯一的。如果使用与现有值相同的键将新值插入全局值集合，则旧值将被覆盖并最终丢失。

Notice

高级用法

全局变量系统包含一个名为 getHashMap() 的函数，该函数返回存储变量的基础 Java HashMap。您可以使用此函数获取基础 HashMap，以便访问更多高级功能。要查看 Java HashMap 类中提供的所有可用函数的完整列表，请参阅HashMap的JavaDocs。

避免内存泄漏

全局变量系统不是智能的。除非被覆盖或者有意删除，它会无限期地保留存储的变量。该系统不会自动删除变量，除非显式告知系统这么做。考虑以下示例：

  • 脚本A将变量设置到全局变量系统中，供脚本B使用。
  • 脚本B检索变量并使用它。
  • 脚本B停止运行或其他情况导致不再使用变量。
  • 脚本A继续处理其他任务。

在上述示例中，全局变量仍然存在于全局变量系统中，因为脚本A和脚本B都没有清除系统中的变量。在这种情况下，该变量是有泄漏的：它仍然存在并且可以被读取，但不再被使用。在编程中，这被称为内存泄漏，因为这会导致不必要的内存使用。而且这是可以避免的。

回到上面的例子：因为脚本B是使用数据的脚本，脚本A无法知道脚本B何时已经看到了这些数据。因此，当脚本B完成数据的获取时，脚本B有责任将该变量从全局变量系统中移除。您可以在上面的代码中看到，一旦打印了test变量，就会执行此操作。

一般而言，在使用全局变量系统时，您应确保在代码的某处，当不再需要旧变量时将其移除。

可用函数

以下是全局变量系统中可用函数的列表：

set(key, value)

将具有指定键（名称）的新值插入全局变量集合中。此函数将始终覆盖具有相同键的现有变量。

  • 参数：
    • key: 要设置的全局变量的键
    • value: 要设置的变量的值
  • 返回值： 具有给定键之前设置的值，如果不存在则返回None
警告

set(key, value) 函数将覆盖具有相同键的现有值！

set(key, value, override)

将具有指定键（名称）的新值插入全局变量集合，可选择覆盖现有值。

  • 参数：
    • key: 要设置的全局变量的键
    • value: 要设置的变量的值
    • override: 如果应覆盖具有给定键的现有变量，请传入True。如果不应覆盖具有相同键的现有变量，请传入False
  • 返回值： 具有给定键之前设置的值，如果不存在则返回None

remove(key)

移除具有指定键（名称）的全局变量。

  • 参数:

    • key: 要移除的全局变量的键

  • 返回值: 被移除的变量的值，如果没有被移除的全局变量，则返回None

get(key)

根据给定的键（名称）获取一个全局变量。

  • 参数:

    • key: 要获取的全局变量的键

  • 返回值: 根据给定键获取的变量，如果在给定的键下没有找到值，则返回None

getKeys()

获取当前设置的所有全局变量键（名称）的列表。

  • 返回值: 当前存储的所有全局变量键的不可变1集合。如果没有设置全局变量，则返回一个空集合。

getValues()

获取当前设置的所有全局变量值的列表。

  • 返回值: 当前存储的所有全局变量值的不可变1集合。如果没有全局变量，则返回一个空集合。

getHashMap()

获取存储所有全局变量的底层 Java HashMap 数据结构。

  • 返回值: 底层 HashMap，它是可变2的。

contains(key)

检查是否使用给定的键（名称）当前存储了一个全局变量。

  • 返回值: 如果存在具有给定键的全局变量，则返回True，如果不存在，则返回False

containsValue(value)

检查当前是否存在具有给定值的全局变量。

  • 返回： 如果存在具有给定值的全局变量，则为 True，如果不存在则为 False

purge()

清除全局变量系统中的所有变量。 类似于对系统进行硬“重置”。

摘要

  • 全局变量系统允许变量在脚本之间进行共享。
  • 全局变量系统的访问方式与 PySpigot 的任何管理器相同。
  • 基本用法涉及 set、get 和 remove 函数。
  • 全局变量的键/名称是唯一的。 如果使用与现有变量相同的键插入新变量，旧值将丢失。
  • 存储在全局变量系统中的变量的值会自动更新，对于访问这些变量的脚本来说，更改会自动可见，无需重新调用 set 函数。
  • 当脚本完成使用全局变量时，应删除全局变量，以避免内存泄漏。
  • 全局变量系统使用 Java HashMap，并且可以使用 getHashMap 函数访问这个底层的 HashMap。

  1. 这里的不可变是指对返回的集合/列表进行的任何更改不会反映在全局变量系统中。换句话说，该集合/列表不是由全局变量 HashMap 支持的。 ↩↩

  2. 这里的可变是指对返回的 HashMap 进行的任何更改都将反映在全局变量系统中。 ↩