---

core.h File Reference

Core, low-level Gale functionality. More...

#include "gale/types.h"
#include "oop.h"

Go to the source code of this file.

Compounds
struct	gale_packet
Initialization
First call gale_init(), then initialize liboop, then call gale_init_signals().
#define	GALE_BANNER
	The standard Gale banner (including the copyright message), good for including in a usage message. More...
void	gale_init (const char *name,int argc,char * const *argv)
	Initialize Gale. More...
void	gale_init_signals (oop_source *oop)
	Set up standard signal handlers. More...
struct gale_text	gale_var (struct gale_text name)
	Get an environment or configuration variable.
void	gale_set (struct gale_text var,struct gale_text value)
	Set an environment or configuration variable.
struct gale_environ*	gale_save_environ (void)
	Save the environment as a whole. More...
void	gale_restore_environ (struct gale_environ *env)
	Restore the environment from a saved state. More...
Gale Protocol
The gale_link structure represents the protocol state of an active connection to a Gale server; it depends on a physical connection (socket file descriptor) maintained by other means.
struct gale_link*	new_link (struct oop_source *oop)
	Create a new link. More...
void	delete_link (struct gale_link *)
	Close a link immediately (closes the file descriptor in use, if any). More...
void	link_shutdown (struct gale_link *)
	Close a link gracefully. More...
void	link_set_fd (struct gale_link *,int fd)
	Attach a protocol link to a physical file descriptor. More...
int	link_get_fd (struct gale_link *)
	Get the file descriptor in use by a link (if any). More...
void	link_on_error (struct gale_link *, void *(*)(struct gale_link *,int,void *), void *)
	Create a new link. More...
void	link_put (struct gale_link *,struct gale_packet *)
	Transmit a message. More...
void	link_will (struct gale_link *,struct gale_packet *)
	Register a 'will' message. More...
void	link_subscribe (struct gale_link *,struct gale_text spec)
	Subscribe to messages. More...
int	link_queue_num (struct gale_link *)
	Count the unsent messages in a link's outgoing queue.
size_t	link_queue_mem (struct gale_link *)
	Count the total memory size of the unsent messages in a link's outgoing queue.
struct gale_time	link_queue_time (struct gale_link *)
	Return the time when the oldest unsent message in a link's outgoing queue was sent.
void	link_queue_drop (struct gale_link *)
	Drop the oldest unsent message from a link's outgoing queue.
void	link_on_empty (struct gale_link *, void *(*)(struct gale_link *,void *), void *)
	Create a new link. More...
void	link_on_message (struct gale_link *, void *(*)(struct gale_link *,struct gale_packet *,void *), void *)
	Create a new link. More...
void	link_on_will (struct gale_link *, void *(*)(struct gale_link *,struct gale_packet *,void *), void *)
	Create a new link. More...
void	link_on_subscribe (struct gale_link *, void *(*)(struct gale_link *,struct gale_text,void *), void *)
	Create a new link. More...
Sticky Categories
This functionality isn't really implemented yet, so it's not documented, either.
void	ltx_publish (struct gale_link *,struct gale_text spec)
void	ltx_watch (struct gale_link *,struct gale_text category)
void	ltx_forget (struct gale_link *,struct gale_text category)
void	ltx_complete (struct gale_link *,struct gale_text category)
void	ltx_assert (struct gale_link *,struct gale_text cat,struct gale_data cid)
void	ltx_retract (struct gale_link *,struct gale_text cat,struct gale_data cid)
void	ltx_fetch (struct gale_link *,struct gale_data cid)
void	ltx_miss (struct gale_link *,struct gale_data cid)
void	ltx_supply (struct gale_link *,struct gale_data cid,struct gale_data data)
int	lrx_publish (struct gale_link *,struct gale_text *spec)
int	lrx_watch (struct gale_link *,struct gale_text *category)
int	lrx_forget (struct gale_link *,struct gale_text *category)
int	lrx_complete (struct gale_link *,struct gale_text *category)
int	lrx_assert (struct gale_link *,struct gale_text *cat,struct gale_data *cid)
int	lrx_retract (struct gale_link *,struct gale_text *cat,struct gale_data *cid)
int	lrx_fetch (struct gale_link *,struct gale_data *cid)
int	lrx_miss (struct gale_link *,struct gale_data *cid)
int	lrx_supply (struct gale_link *,struct gale_data *cid,struct gale_data *data)

---

Detailed Description

Core, low-level Gale functionality.

---

Define Documentation

#define GALE_BANNER

Initializer: ( \ "Gale version " VERSION ", copyright 1997-2001 Dan Egnor\n" \ "This software comes with ABSOLUTELY NO WARRANTY. You may redistribute\n" \ "it under certain conditions. Run \"gale-config --license\" for information." \ ) The standard Gale banner (including the copyright message), good for including in a usage message.

---

Function Documentation

void delete_link ( struct gale_link * l )

Close a link immediately (closes the file descriptor in use, if any). Parameters: l   The link to close. See also: link_shutdown()

void gale_init ( const char * s, int argc, char *const * argv )

Initialize Gale. Parameters: name   The program name (e.g. "gsub"). argc   Argument count from main(). argv   Argument vector from main(). See also: gale_init_signals()

void gale_init_signals ( oop_source * source )

Set up standard signal handlers. This is distinct from gale_init() because it requires liboop initialization, but liboop can't be initialized until after Gale is. Parameters: oop   Liboop event source to use for signal dispatch. See also: gale_init()

void gale_restore_environ ( struct gale_environ * env )

Restore the environment from a saved state. Parameters: env   Snapshot of the environment from gale_save_environ(). See also: gale_save_environ()

struct gale_environ * gale_save_environ ( void )

Save the environment as a whole. Returns: Snapshot of the environment. See also: gale_restore_environ()

int link_get_fd ( struct gale_link * l )

Get the file descriptor in use by a link (if any). Parameters: l   The link to examine. Returns: The file descriptor in use by the link, or -1 if detached. See also: link_set_fd()

void link_on_empty ( struct gale_link * l, void *(*)(struct gale_link *,void *), void * )

Create a new link. The link will be detached when it is created. Use link_set_fd() to associate the link with a physical connection to a Gale server. Parameters: oop   The liboop event source to use for processing messages. Returns: A new gale_link structure, ready to handle protocol traffic.

void link_on_error ( struct gale_link * l, void *(*)(struct gale_link *,int,void *), void * )

Create a new link. The link will be detached when it is created. Use link_set_fd() to associate the link with a physical connection to a Gale server. Parameters: oop   The liboop event source to use for processing messages. Returns: A new gale_link structure, ready to handle protocol traffic.

void link_on_message ( struct gale_link * l, void *(*)(struct gale_link *,struct gale_packet *,void *), void * )

Create a new link. The link will be detached when it is created. Use link_set_fd() to associate the link with a physical connection to a Gale server. Parameters: oop   The liboop event source to use for processing messages. Returns: A new gale_link structure, ready to handle protocol traffic.

void link_on_subscribe ( struct gale_link * l, void *(*)(struct gale_link *,struct gale_text,void *), void * )

Create a new link. The link will be detached when it is created. Use link_set_fd() to associate the link with a physical connection to a Gale server. Parameters: oop   The liboop event source to use for processing messages. Returns: A new gale_link structure, ready to handle protocol traffic.

void link_on_will ( struct gale_link * l, void *(*)(struct gale_link *,struct gale_packet *,void *), void * )

Create a new link. The link will be detached when it is created. Use link_set_fd() to associate the link with a physical connection to a Gale server. Parameters: oop   The liboop event source to use for processing messages. Returns: A new gale_link structure, ready to handle protocol traffic.

void link_put ( struct gale_link * l, struct gale_packet * m )

Transmit a message. Parameters: l   The link to send the message with. m   The message to enqueue on the link. It will be sent in the background (using liboop). See also: link_on_message()

void link_set_fd ( struct gale_link * l, int fd )

Attach a protocol link to a physical file descriptor. The link will reset its state and use the supplied file descriptor for I/O. Parameters: l   The link to associate with a file descriptor. fd   The file descriptor to use, or -1 to detach the link. See also: link_get_fd()

void link_shutdown ( struct gale_link * l )

Close a link gracefully. Unlike delete_link(), this function closes the outgoing half of the connection and waits for the other end to finish sending. When the link is fully shut down, the function (if any) registered via link_on_empty() will be called. Parameters: l   The link to shut down. See also: delete_link()

void link_subscribe ( struct gale_link * l, struct gale_text spec )

Subscribe to messages. You will not receive messages on a link until you subscribe. Parameters: l   The link to subscribe to messages with. spec   The subscription. See also: link_on_subscribe(), link_on_message().

void link_will ( struct gale_link * l, struct gale_packet * m )

Register a 'will' message. A 'will' is a message that is sent to the server, but is only transmitted when the link is broken. This can be used to notify others when you lose connectivity. Parameters: l   The link to register a 'will' message with. m   The 'will' message to register. It will be sent in the background (using liboop). See also: link_on_will()

struct gale_link * new_link ( struct oop_source * oop )

Create a new link. The link will be detached when it is created. Use link_set_fd() to associate the link with a physical connection to a Gale server. Parameters: oop   The liboop event source to use for processing messages. Returns: A new gale_link structure, ready to handle protocol traffic.

---