PyFCGI/include/responder.h

/*
 * Copyright (C) 2019 Weber Yann
 * 
 * This file is part of PyFCGI.
 * 
 * PyFCGI is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * any later version.
 * 
 * PyFCGI is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 * 
 * You should have received a copy of the GNU Affero General Public License
 * along with PyFCGI.  If not, see <http://www.gnu.org/licenses/>.
 */
/**@defgroup work_master_proc Worker handler process
 * @brief This process use the @ref responder_loop() function as "main" function
 *
 * @section work_master_spawn Spawning workers
 * This subprocess handle worker spawning using @ref spawn(). A POSIX semaphore
 * allow to know when the worker pool is idle or not :
 * 
 * @subsection work_master_spawn_sem Semaphore idle & busy detection
 * When a new worker is ready (idle) it add 1 to the semaphore, when processing
 * a request it substract 1 to the semaphore (done in @ref work() function in
 * @ref worker_process )
 *
 * When semtimedop blocks on wait_for_zero operation it means that the pool is
 * idle. Instead, if the semtimedop returns imediately it means a new worker
 * can be spawned.
 *
 * @ingroup processes
 * @ingroup main_proc
 */
/**@file responder.h
 * @ingroup work_master_proc
 */
#ifndef _RESPONDER__H___
#define _RESPONDER__H___
#include "config.h"

#include <fcgi_stdio.h> /* fcgi library; put it first*/

#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <syslog.h>
#include <errno.h>
#include <time.h>
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>

#include "logger.h"
#include "pyworker.h"


extern int pyfcgi_semid;

void init_context();

/**@brief The responder loop
 * @ingroup work_master_proc
 * The main function of the fcgi app fork child
 * @param int max_requests : exit normally after this number of requests. If
 * 0 given never exit.
 * @param char* python_entrymodule a python module name
 * @param char* python_entrymodule a python callable name from entry module
 * @param unsigned int max_requests before exiting worker
 * @param unsigned int minimum workers count
 * @param unsigned int maximum wrokers count
 * @return 0 on success
 */
int responder_loop();


/**@brief Spawn a worker given an entrypoint
 * @ingroup work_master_proc
 * Spawn a new worker process and prepare ENV & request forwarding
 * @param int worker uid
 * @param int semid for FCGI access
 * @return child PID
 */
pid_t spawn(int, int);

/**@brief Generate a new semaphore from given key
 * @ingroup work_master_proc
 * @note set pyfcgi_semid
 * @return int semid
 */
int new_semaphore();

/**@brief Exit after closing all stuff like semaphores
 * @ingroup work_master_proc
 */
void clean_exit(int);

/**@brief Handle signals and forward it to workers */
void pool_sighandler(int signum);

#endif