Key Concepts

Notes

These documents are a work in progress, and we are trying to improve upon them on a daily basis. However, given our capacity and workload, there are bound to be things which get missed or checked in which should not have been checked in. If you find mistakes or documents wanting information, and you would like to help, you can do so in two ways

1. Submit corrections. When you update anything and submit a PR, we will review it and if all looks good, it will be added. This is the fastest way that one can expect changes to be in.
2. Submit tickets. If you are not sure how to make updates, or if you are short on time, please raise an issue in the repo, with details and what you think needs to be the expected text. We will try and update the literature to reflect any changes that we feel are merited. Note that this route will take longer than the first approach and there are no guarantees on the timeline.

Non-blocking functions

To explain the concept of a non-blocking function, we will use two example functions Foo() and Bar().

Say Foo() waits for 5 seconds then prints "foo", and Bar() simply prints "bar".

We run the following:

Foo();
Bar();

If Foo() is a blocking (synchronous/standard) function, our output will be:

"foo"
"bar"

If Foo() is a non-blocking (asynchronous) function, our output will be:

"bar"
"foo"

In the case of a non-blocking function, since Foo() doesn't stop the program from moving forward, you might wonder how you can actually know when it's done. That's where callbacks come in.

To get the result of what Foo() is doing, you need to give the library a way to notify you when the operation completes.

This is called setting up a hook. When Foo() finishes its work, it will "call you back" by running a function you provided, known as a callback function.

This way, your program can keep doing other tasks, and once Foo() is done, your callback function gets executed to handle the result or next steps.

Callbacks & Hooks

In the Corelink C# client, callbacks are expressed as Action<> delegates assigned to properties on CorelinkClient. For example, to be notified whenever data arrives on a receiver stream:

CorelinkClient.OnServerPush = (func, msg) =>
{
    Console.WriteLine($"[Server push] {func}: {msg}");
};

Server-initiated events also have typed callbacks:

// Fired when a new sender matching your receiver's workspace/type becomes available
CorelinkClient.OnUpdate = (receiverID, streamID, user, apps, type, meta) =>
{
    Console.WriteLine($"New sender available: streamID={streamID}, type={type}");
};
 
// Fired when a receiver subscribes to your sender
CorelinkClient.OnSubscriber = (senderID, receiverID, user, apps, meta) =>
{
    Console.WriteLine($"New subscriber: receiverID={receiverID}");
};
 
// Fired when a stream is no longer active
CorelinkClient.OnStale = (streamID) => Console.WriteLine($"Stream {streamID} is stale.");
 
// Fired when a receiver unsubscribes
CorelinkClient.OnDropped = (streamID) => Console.WriteLine($"Stream {streamID} dropped.");

Set these before calling ConnectAsync so no events are missed.

async/await

In the Corelink C# client, we use C#'s async/await keywords and the Task type to achieve asynchronous, non-blocking behavior.

When you call an async method, it can suspend its own execution at any await point and return control to the caller — without blocking the calling thread. The calling thread is free to do other work while the awaited operation completes in the background.

Here's how async/await provides non-blocking behavior:

using System;
using System.Threading.Tasks;
 
async Task FooAsync()
{
    await Task.Delay(5000); // Simulates a long operation (does not block the thread)
    Console.WriteLine("foo");
}
 
void Bar()
{
    Console.WriteLine("bar");
}
 
async Task Main()
{
    Task fooTask = FooAsync(); // Launch FooAsync without blocking
    Bar();                      // Executes immediately, before FooAsync finishes
    await fooTask;              // Optionally wait for FooAsync to complete
}

Output:

"bar"
"foo"

In this example, FooAsync() is launched and immediately yields at await Task.Delay(5000), so Bar() runs right away. The await fooTask line later waits for FooAsync to finish when the result is actually needed.

Task and Task<T> in C# serve the same purpose as std::future<void> and std::future<T> in C++. The await keyword is analogous to calling .get() on a future, but with a key difference: await suspends the current method without blocking the underlying thread, allowing the .NET runtime to schedule other work on it. This makes it far more efficient than spinning or blocking.

Using async/await with Corelink

All Corelink control functions return Task or Task<T> and should be awaited:

// Connect and authenticate
bool ok = await CorelinkClient.ConnectAsync("corelink.hsrn.nyu.edu", 20012, "username", "password");
 
// List workspaces
string[] workspaces = await CorelinkClient.ListWorkspacesAsync();
 
// Create a sender
var senderResp = await CorelinkClient.SenderAsync("MyWorkspace", "myType", proto: "ws");
 
// Disconnect
await CorelinkClient.DisconnectAsync();

Forgetting to await a Task-returning method means the operation may not complete before your code moves on, and any exceptions it throws will be silently swallowed. Always await Corelink calls.