GLOBUS_XIO_API_ASSIST(3)

💖 GLOBUS_XIO_API_ASSIST 💖 (3)

okay bestie, welcome to the Library Functions Manual for GLOBUS_XIO_API_ASSIST 🦋 — this one is literally just called XIO Examples and it's here to help you understand the globus_xio api. that's the whole vibe. no cap.

---

✨ NAME ✨

GLOBUS_XIO_API_ASSIST — XIO Examples

• XIO Examples. 🎀

---

🌸 SYNOPSIS 🌸

Detailed Description

XIO Examples.

Help understanding the globus_xio api. that's it, that's the mission 🫶

---

🧚 Stack Construction 🧚

so the driver stack for a given XIO handle? it gets constructed using a globus_xio_stack_t. every driver gets loaded by name and then pushed onto a stack. iconic behavior honestly.

Stack setup example:

// First load the drivers
globus_xio_driver_load("tcp", &tcp_driver);
globus_xio_driver_load("gsi", &gsi_driver);

//build the stack
globus_xio_stack_init(&stack);
globus_xio_stack_push_driver(stack, tcp_driver, NULL);
globus_xio_stack_push_driver(stack, gsi_driver, NULL);

---

👑 Servers 👑

a server data structure gives you functionality for passive opens. a server gets initialized and bound to a protocol stack and a set of attributes with the function globus_xio_server_create(). once a server is created, many "connections" can be accepted, and every connection results in an initialized handle that you can later open. slay 💅

globus_xio_server_t             server;
globus_xio_attr_t               attr;

globus_xio_attr_init(&attr);
globus_xio_server_create(&server_handle, attr, stack);
globus_xio_server_accept(&handle, server);

---

🦋 Handle Construction 🦋

there are two ways to create a handle, bestie. pick your fighter:

1. the first one is for use as a client (aka someone doing an active open). the function globus_xio_handle_create() is used to create such a handle and bind that handle to a protocol stack.

globus_xio_handle_create(&handle, stack);

2. the second way to create a handle is for use as a server (aka someone doing a passive open). this one gets created by accepting a connection on a server_handle with the function globus_xio_server_accept() or globus_xio_server_register_accept().

mutable attrs can be altered via a call to globus_xio_handle_cntl() — we get to that later, don't worry 🍓

globus_xio_server_accept(&xio_handle, server_handle);

once a handle is initialized the user can call globus_xio_open() to begin the open process. periodt.

---

⏰ Timeouts ⏰

you can set a timeout value for any I/O operation, fr fr. every single I/O operation (open close read write) can have its own timeout value. and if no timeout is set? the operation is allowed to infinitely block. (yes, infinitely. the main character energy is real but so is the risk 😭)

when time expires, the outstanding operation is canceled. if the timeout callback for the given operation is not NULL, it gets called first — to notify you that the operation timed out and give you a chance to ignore that timeout. if it is canceled, you'll get the callback you registered for the operation as well, but it'll come with an error indicating that it has been canceled. 💀

it's possible that part of an I/O operation will complete before the timeout expires. in this case the operation can still be canceled. you'll receive your IO callback with an error set and the length value appropriately set to indicate how much of the operation completed. so like… read the length, bestie.

timeouts are registered by using the following handle_cntl values:

• GLOBUS_XIO_ATTR_SET_TIMEOUT_ALL
• GLOBUS_XIO_ATTR_SET_TIMEOUT_OPEN
• GLOBUS_XIO_ATTR_SET_TIMEOUT_CLOSE
• GLOBUS_XIO_ATTR_SET_TIMEOUT_READ
• GLOBUS_XIO_ATTR_SET_TIMEOUT_WRITE
• GLOBUS_XIO_ATTR_SET_TIMEOUT_ACCEPT

each of these cntls expects three parameters:

• globus_xio_timeout_callback_t callback_function
• globus_reltime_t * delay_time
• void * callback_arg

---

🌈 Data Descriptor 🌈

the data descriptor ADT gives you a means of attaching/extracting meta data to a read or write operation. things like offset, out of band message, and other driver specific meta data are all contained in the data descriptor. obsessed honestly.

data descriptors are passed to globus_xio in globus_xio_read() and globus_xio_write(). within the globus_xio framework it is acceptable to pass NULL instead of a valid data_descriptor,

Example:

globus_xio_data_descriptor_init(&desc);
globus_xio_data_descriptor_cntl(desc,
    tcp_driver,
    GLOBUS_XIO_TCP_SET_SEND_FLAGS,
    GLOBUS_XIO_TCP_SEND_OOB);

---

💜 User Attributes 💜

Globus XIO uses a single attribute object for all of its functions. attributes give you an extensible mechanism to alter default values which control parameters in an operation. so much power, honestly 💅

in most of the Globus XIO user API functions you pass an attribute as a parameter. in many cases you may ignore the attribute parameter and just pass in NULL. but at times you'll wish to tweak the operation — and the attribute structure is used for exactly that tweaking.

there are only three attribute functions: globus_xio_attr_init, globus_xio_attr_cntl and globus_xio_attr_destroy. the init and destroy functions are very simple and require little explanation. before an attribute can be used it must be initialized, and to clean up all memory associated with it you must call destroy on it. clean up after yourself, bestie 🧹✨

the function globus_xio_attr_cntl manipulates values in the attribute. for more info on it see globus_xio_attr_cntl.

---

🎀 Author 🎀

Generated automatically by Doxygen for globus_xio from the source code.

---

okay that's the whole page!! and just so you have the receipts, this was globus_xio, Version 6.6 — go off, version 6.6, you ate 💖✨🌈 bye bestie, go build a stack 🫶👑