workflow_wal.h File Reference

Write-Ahead Log (WAL) persistence for the AI Workflow engine. More...

#include <stdint.h>
#include "csilk/app/workflow.h"

Include dependency graph for workflow_wal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	CSILK_WF_MAGIC   0x5746414C /* "WFAL" */
	Magic number identifying a WAL file ("WFAL" in ASCII).

Enumerations
enum	csilk_wf_event_type_t {   WF_EV_START = 1 , WF_EV_NODE_START = 2 , WF_EV_NODE_FINISH = 3 , WF_EV_PAUSE = 4 ,   WF_EV_END = 5 }
	Event types recorded in the workflow WAL. More...

Functions
struct	__attribute__ ((packed))
	Packed binary header prefixed to every WAL record.
int	_wf_wal_append (const char *wal_path, csilk_wf_event_type_t type, const void *payload, size_t len)
	Append a WAL record to the log file.

Variables
	csilk_wf_wal_header_t

Detailed Description

Write-Ahead Log (WAL) persistence for the AI Workflow engine.

Provides fault-tolerant execution logging for csilk_wf_t workflows. Every workflow event (start, node-start, node-finish, end) is appended to a binary log file before it is processed. If the server crashes, interrupted workflows can be resumed by replaying the WAL.

The WAL format is a sequence of packed binary records, each prefixed by a csilk_wf_wal_header_t. The payload is event-type-specific JSON (e.g., node ID, input/output data). This header is internal to the workflow implementation and is not intended for direct use.

Copyright

MIT License

Macro Definition Documentation

CSILK_WF_MAGIC

#define CSILK_WF_MAGIC   0x5746414C /* "WFAL" */

Magic number identifying a WAL file ("WFAL" in ASCII).

Enumeration Type Documentation

csilk_wf_event_type_t

enum csilk_wf_event_type_t

Event types recorded in the workflow WAL.

Each event is written before the corresponding action is performed (write-ahead semantics), ensuring that on recovery we can identify partially-completed executions.

Enumerator
WF_EV_START	Workflow execution started.
WF_EV_NODE_START	A specific node began executing (carries node ID and input in payload).
WF_EV_NODE_FINISH	A specific node completed (carries node ID and output in payload).
WF_EV_PAUSE	Workflow execution paused for manual input.
WF_EV_END	Workflow execution completed or was aborted.

Function Documentation

__attribute__()

struct __attribute__

(

(packed)

)

Packed binary header prefixed to every WAL record.

The header is followed by payload_len bytes of event-specific data (typically a JSON string). Total record size = sizeof(header) + payload_len.

Note

attribute((packed)) eliminates padding so the on-disk format is consistent across architectures and compilers.

< Must equal CSILK_WF_MAGIC for file validation.

< csilk_wf_event_type_t value.

< Unix timestamp (seconds since epoch) of the event.

< Byte length of the payload that follows this header.

_wf_wal_append()

int _wf_wal_append	(	const char *	wal_path,
		csilk_wf_event_type_t	type,
		const void *	payload,
		size_t	len
	)

Append a WAL record to the log file.

Internal helper used by workflow.c to persist each event. Creates the log file if it does not yet exist. The WAL directory is set via csilk_wf_set_persistence.

Parameters

wal_path	Path to the WAL file.
type	Event type enumerator.
payload	Event-specific data (typically a JSON string).
len	Byte length of payload.

Returns

0 on success, -1 on I/O error.

Append a WAL record to the log file.

Algorithm:

1. Open (or create) the WAL file in O_WRONLY | O_APPEND mode.
2. Write a fixed-size csilk_wf_wal_header_t (magic, type, timestamp, payload_len).
3. If payload_len > 0 and payload is non-NULL, write the payload bytes immediately after the header.
4. fdatasync() the file to flush the data to disk before closing.

Parameters

wal_path	Absolute path to the WAL file.
type	Event type (e.g., WF_EV_START, WF_EV_NODE_FINISH).
payload	Opaque payload data to persist (may be NULL if len is 0).
len	Number of payload bytes.

Returns

0 on success, -1 if wal_path is NULL or any write fails.

Note

Not thread-safe for concurrent writes to the same file — callers should serialize access at the workflow context level.

Variable Documentation

csilk_wf_wal_header_t

csilk_wf_wal_header_t