libs/html-threaded/include/html_gen.h

124 lines

1/*
2 * html_gen.h - Parallel HTML file writer using pthreads
3 *
4 * This library provides thread-pooled file writing for HTML generation.
5 * Lua generates the HTML strings, C handles parallel I/O.
6 *
7 * Usage:
8 * 1. Create context with htmlgen_init(num_threads)
9 * 2. Add files with htmlgen_add_file(ctx, path, content, content_len)
10 * 3. Write all files with htmlgen_write_all(ctx)
11 * 4. Check progress with htmlgen_get_progress(ctx)
12 * 5. Cleanup with htmlgen_destroy(ctx)
13 */
14
15#ifndef HTML_GEN_H
16#define HTML_GEN_H
17
18#include <stdint.h>
19#include <stddef.h>
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25/* {{{ Opaque context handle */
26typedef struct HtmlGenContext HtmlGenContext;
27/* }}} */
28
29/* {{{ Error codes */
30typedef enum {
31 HTMLGEN_SUCCESS = 0,
32 HTMLGEN_ERROR_INIT_FAILED = -1,
33 HTMLGEN_ERROR_OUT_OF_MEMORY = -2,
34 HTMLGEN_ERROR_WRITE_FAILED = -3,
35 HTMLGEN_ERROR_INVALID_CONTEXT = -4,
36 HTMLGEN_ERROR_ALREADY_RUNNING = -5,
37} HtmlGenResult;
38/* }}} */
39
40/* {{{ Statistics structure */
41typedef struct {
42 uint32_t total_files;
43 uint32_t files_written;
44 uint32_t files_failed;
45 uint64_t total_bytes;
46 double elapsed_seconds;
47} HtmlGenStats;
48/* }}} */
49
50/* {{{ Core API */
51
52/*
53 * Initialize HTML generator context
54 * @param num_threads Number of worker threads (0 = auto-detect CPU cores)
55 * @return Context handle or NULL on failure
56 */
57HtmlGenContext* htmlgen_init(int num_threads);
58
59/*
60 * Add a file to the write queue
61 * @param ctx Context handle
62 * @param filepath Full path to output file
63 * @param content HTML content to write
64 * @param content_len Length of content in bytes
65 * @return HTMLGEN_SUCCESS or error code
66 *
67 * Note: Content is copied internally, caller can free after this returns
68 */
69HtmlGenResult htmlgen_add_file(HtmlGenContext* ctx,
70 const char* filepath,
71 const char* content,
72 size_t content_len);
73
74/*
75 * Write all queued files using thread pool
76 * Blocks until all files are written
77 * @param ctx Context handle
78 * @return HTMLGEN_SUCCESS or error code
79 */
80HtmlGenResult htmlgen_write_all(HtmlGenContext* ctx);
81
82/*
83 * Get current progress (0.0 to 1.0)
84 * Can be called from another thread while write_all is running
85 * @param ctx Context handle
86 * @return Progress as fraction (0.0 = not started, 1.0 = complete)
87 */
88float htmlgen_get_progress(HtmlGenContext* ctx);
89
90/*
91 * Get statistics after write_all completes
92 * @param ctx Context handle
93 * @param stats Output statistics structure
94 * @return HTMLGEN_SUCCESS or error code
95 */
96HtmlGenResult htmlgen_get_stats(HtmlGenContext* ctx, HtmlGenStats* stats);
97
98/*
99 * Clear the file queue (reuse context for another batch)
100 * @param ctx Context handle
101 */
102void htmlgen_clear(HtmlGenContext* ctx);
103
104/*
105 * Destroy context and free all resources
106 * @param ctx Context handle
107 */
108void htmlgen_destroy(HtmlGenContext* ctx);
109
110/*
111 * Get human-readable error string
112 * @param result Error code
113 * @return Static string describing the error
114 */
115const char* htmlgen_error_string(HtmlGenResult result);
116
117/* }}} */
118
119#ifdef __cplusplus
120}
121#endif
122
123#endif /* HTML_GEN_H */
124