LineProcMirror

类私有源码

pbuf: syncstream.LineProcBuffer
buffer = pbuf.mirror

进程安全缓存的镜像。

危险

该mirror由LineProcBuffer初始化，且用于管理要写入到buffer的行数据。用户不需要、也不应使用该类来实例化对象。请总是使用pbuf.mirror来获取mirror对象。

别名

该类可以按以下方式之一获取

import syncstream


syncstream.LineProcMirror
syncstream.mproc.LineProcMirror

参数

输入

参数	类型	必选	说明
q_maxsize	int		队列的最大长度。该值和queue.qsize意义相同。
aggressive	bool		若设为True，则启用积极模式，亦即是说，只要有新的数据写入该mirror，就会立即传递给缓存。若设为False，则只会在新写一整行的时候、才传递给缓存。
timeout	int | None		网络同步事件的时限。该值和queue.put(timeout)的参数意义一致。
_queue	Queue | None		用来与缓存通信的队列。该对象是一个multiprocessing.Queue()、或由multiprocessing.Manager()给出。队列对象由LineProcBuffer构造。
_state	dict[str, Any] | None		由multiprocessing.Manager()给出的共享状态字典。该字典对象由 LineProcBuffer构造。
_state_lock	Lock | None		状态字典的读/写锁。由multiprocessing.Manager()给出。该锁对象由LineProcBuffer构造。

方法

clear

buffer.clear()

清空临时缓存。

该方法会清空mirror的临时缓存。若mirror按aggresive模式工作，则临时缓存不会用到。在此情形下，该方法将不会对mirror产生任何影响。

该方法是线程安全的。且不同进程的镜像并不会共享相同的临时缓存。且需要注意的是，该方法不会清空共享队列的内容。

---

new_line

buffer.new_line()

清空当前的临时缓存，并人为地触发一个“新行”信号。若当前的临时缓存包含数据，则会先将数据移动到存储区，然后再创建新行。若当前的临时缓存的已经是新行，则不做任何处理。

该方法等价于

if buffer.last_line.tell() > 0:
    write('\n')

---

flush

buffer.flush()

刷新当前正在写入行的数据流（临时缓存）。

---

send_eof

buffer.send_eof()

发送安全关闭信号。

应当在子进程的结尾使用该信号。该方法用来通知缓存子进程的工作已经安全完成。

危险

• 在每个子进程的结尾，应当总是使用send_eof()或send_error()。否则，主线程（的缓存）有可能造成死锁。
• 在每个子进程的结尾，应当只使用一次send_eof()或send_error()。例如，若调用过send_error()，则不应再调用send_eof()。从同一子进程发送超过一个关闭信号，可能引发严重故障。

---

send_error

buffer.send_error(error: Exception)

向主缓存发送异常对象。

发送缓存过的异常对象。该方法需要用于try / except块中。错误对象将会在主缓存中捕获为一条信息。

危险

参见send_eof()。

输入

参数	类型	必选	说明
error	Exception		要发送的异常对象。

---

send_warning

buffer.send_warning(warning: Warning)

向主缓存发送标准警告对象。

发送缓存过的警告对象。建议在每当需要写入警告日志时、使用该方法。警告对象将会在主缓存中捕获为一条信息。

警告

该方法只能捕获标准库定义的警告对象。某些不同的警告对象，例如logging.warning所写的warning信息，则无法被该方法收集。

输入

参数	类型	必选	说明
warning	Warning		要发送的警告对象。

---

send_data

buffer.send_data(data: str)

向主缓存发送数据。

该方法等价于在进程安全的保护机制下、同步地调用主缓存（LineProcBuffer）的以下方法：

super(LineProcBuffer, pbuf).write(data)

该方法被其他方法隐式调用，故用户不应使用该方法。

输入

参数	类型	必选	说明
data	str		要发送到主缓存的str。

---

read

line: str = buffer.read()

该方法只会读取、当前保留在mirror的临时缓存内的数据。若属性aggressive为True，则read()方法将总是返回空值。

输出

参数	类型	说明
line	str	当前mirror的临时存储结果。在临时存储内的数据还没有发送到主缓存。

---

write

n_bytes: int = buffer.write(data: str)

写缓存的方法。源数据的形式与文字IO的数据形式相同。若属性aggressive为True，每次调用write()时，都将会使得流内的数据发送到主缓存。否则，只在每当data包含断行符的时候、才会将流的数据发送到主缓存。

该方法是线程安全的。

输入

参数	类型	必选	说明
data	str		要写入的信息。会自动检测其中包含的断行符。

输出

参数	类型	说明
n_bytes	int	所要写入缓存的byte数目。该值直接从输入data计算。

属性

aggressive

is_aggressive: bool = buffer.aggressive

积极模式。

该模式只能在初始化的时候设置。若设为True，则积极模式启用，mirror将会在每当收到新的数据时，将信息传递给主缓存。若设为False，则只会在新写一整行的时候、才传递给缓存。

---

timeout

tiemout: int = buffer.timeout

设置给队列的时限。该值和queue.put(timeout)的参数意义一致。

在当前实现中，该值总是设置为None，但用户使用mirror时，可以修改该值。

范例

参见LineProcBuffer。